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

With no annotations provided, the description carries the full burden, and it does so well. 'Presentation-only' and 'cannot change governed execution or evidence' accurately disclose both what the tool does and what it will not do, giving the agent clear safety expectations.

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 compact sentences with no filler. The first sentence front-loads the action and preconditions, and the second adds the essential limitation. Every sentence earns its place.

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 zero-parameter tool with no output schema, the description provides everything needed: what happens, when it should happen, and what side effects it cannot have. No important invocation information 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?

The tool has zero parameters and the schema is already fully covered. With no parameters to document, the description does not need to add parameter explanations; the baseline for zero-parameter tools applies.

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 names a specific action ('Open') and a distinct resource ('MartinLoop Arcade') and scopes it as presentation-only. It differentiates the tool from the run/eval/status siblings by emphasizing it is strictly a display surface, not a control surface.

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?

The description explicitly states the condition under which the tool should be used ('when the host supports MCP Apps'). It also tells the agent not to use it for mutating or governed workflows by clarifying that the Arcade 'cannot change governed execution or evidence'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is largely covered. The description reinforces this with 'reads persisted evidence and never changes run state' and notes the Arcade-only rendering purpose, but adds little beyond what the structured fields already provide.

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?

Three short sentences, front-loaded with the tool's identity and scope, with zero filler. The final clause about not changing run state slightly restates the readOnlyHint annotation, a minor redundancy.

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 values need no explanation, and the description fully covers purpose, scoping input, alternatives, and read-only behavior. Complete for a single-optional-parameter read tool.

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% and the loopId description already documents omission meaning 'latest persisted run', so the description's equivalent statement is redundant. Baseline 3 is appropriate when the schema fully carries parameter meaning.

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 (read) and resource (the read-only evidence projection used by the Arcade view), and explicitly contrasts itself with sibling tools martin_status and martin_run_dossier. An agent can distinguish it from the other evidence-reading tools without opening any 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?

Gives explicit when-to-use (Arcade rendering), when-not/alternatives (martin_status for budget pressure, martin_run_dossier for full evidence), and the loopId-vs-omit choice. Nothing is left to inference.

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

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

The destructiveHint=true annotation could mislead an agent into thinking a process is killed; the description corrects this directly ('This records a request and does not kill a process') and adds audit-context intent. It doesn't address the idempotentHint=false implication of repeat calls, which is a minor remaining gap.

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?

Three sentences, front-loaded with the action and selector constraint, then usage guidance, then the critical behavioral caveat. No redundant restatement of the name or schema.

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?

With an output schema present, return values need not be explained, and the description still covers the selector contract, store-root override, audit fields, and the distinction from martin_pause. Nothing an agent needs to call this 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 already 100%, so the baseline is 3. The description adds framing beyond the schema by stating the 'exactly one selector' grouping and clarifying roles (runsDir changes the run-store root; reason/requestedBy supply audit context), which helps an agent assemble a valid call.

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: 'Write a durable cancellation receipt for one canonical MartinLoop run.' It also distinguishes itself from the sibling martin_pause by name, so an agent can differentiate without opening either 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?

Gives an explicit trigger ('Use when work must be abandoned, not temporarily held') plus the alternative and its selection condition ('use martin_pause for a reversible hold'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already disclose destructiveHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds useful context ('durable' request, triggered by a pause/approval checkpoint) but never explains what state is mutated, whether the request can be rejected, or what permissions are required, leaving a non-trivial gap for a destructive write.

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?

A single front-loaded sentence with no filler, and the trigger condition is placed after the core action. Efficient, though its brevity contributes to the gaps in the other dimensions.

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 values need not be described. Nevertheless, for a six-parameter destructive, non-idempotent write tool, the description omits all parameter guidance and any detail on what the durable request does or how it is consumed, leaving it under-specified for correct invocation.

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% across six parameters (file, latest, loopId, reason, runsDir, requestedBy), so the description is the only place meaning could be added. It explains none of them, not even the const-true 'latest' flag or the purpose of 'reason'/'requestedBy', offering only a faint framing that this is a 'request' object.

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 ('Record') and resource ('continue or resume request for a Martin run'), and the clause 'after a human pause or approval checkpoint' clarifies the state it acts on. It does not explicitly name or distinguish itself from nearby siblings such as martin_pause or martin_cancel, so it stops short of a 5.

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?

The description implies the usage context ('after a human pause or approval checkpoint'), which is genuine situational guidance. However, it names no alternative and gives no when-not condition, so the agent must infer the boundary against martin_pause, martin_cancel, and martin_run.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation risk is known. The description usefully adds that the operation previews by default and only performs the destructive 'gh' call when execute=true, which is valuable context beyond the annotations. It still omits auth requirements (gh CLI), what exactly gets created, and side effects of the dossier body.

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?

Two short sentences with the core action front-loaded and the mode-switch instruction immediately after. No filler; slightly terse given the parameter count it must cover.

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 values need not be explained. But for an 8-parameter, destructive, non-idempotent tool with 0% schema coverage, the description only addresses the execute flag and leaves most input semantics undefined, which is inadequate for correct invocation.

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% across 8 parameters. The description only clarifies one parameter (execute), leaving base, file, title, format, latest, loopId, and runsDir entirely undocumented in both the schema and the description. With such low coverage the description does not compensate for the gap.

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 ('Create or preview a GitHub PR with a MartinLoop dossier body'), which is clear and distinct from siblings like martin_pr_summary and martin_review_pr. It is not tautological and an agent can grasp the action without opening the 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?

The 'Use execute=true to actually call gh' clause tells the agent how to switch from preview to real execution, which implies the safe default. However, there is no explicit guidance on when to choose this tool over sibling PR tools (martin_pr_summary, martin_review_pr), so usage is only partially framed.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description's 'Read-only' phrasing reinforces this without adding conflict. It adds behavioral value by scoping the diagnostic domains and by warning that the output is not proof of completion, which is a meaningful non-obvious trait. With annotations covering safety, this is strong but not maximal.

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?

Three concise sentences deliver purpose, usage timing, exclusions, and next steps with no filler. The most important information is front-loaded, and every sentence earns its place. Reusing 'Read-only' from annotations is minor redundancy but not harmful to an agent scanning prose.

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 tool with zero required parameters, a complete output schema, and read-only/idempotent annotations, the description covers all essential decision-making context. It includes scope, when to invoke, what not to infer, and which sibling to call next. An agent can safely invoke this tool correctly without further clarification.

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%, with all three optional parameters already thoroughly described in the input schema. The description itself adds no parameter-specific guidance, but the schema carries the full burden. This meets the baseline for a fully covered schema.

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 identifies the tool as read-only diagnostics for environment, engine, workspace, and run-store data, which is specific about resources and scope. It lacks an explicit active verb like 'get' or 'run', instead using the noun phrase 'diagnostics', though the intent is unmistakable. It distinguishes from siblings by positioning itself as a first-step diagnostic rather than a completion check.

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?

The description explicitly states when to use the tool: 'Use first for software work, fresh installs, suspicious state, or before retries.' It also provides a clear exclusion: 'Do not use as proof that a task is complete.' It routes the agent to the appropriate next tool based on whether the work is new or failed, making the decision tree explicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context: it requires exactly one selector, explains that runsDir changes the run-store root, and notes that json is the default format. It doesn't describe the return shape, but the output schema exists and the description's added constraints are useful.

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 compact and front-loaded: it states the core action in the first sentence, then selector/format rules, then usage context, then an exclusion. Every sentence earns its place, and the structure moves from what to how to when.

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 read-only, idempotent tool with a full output schema and 100% parameter coverage, the description is complete. It covers selector semantics, format options, default behavior, runsDir override, when to use it, and when not to use it. The only minor gap is not describing the exact content of the formatted summary, but the output schema and the phrase 'evidence summary' cover that sufficiently.

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%, so the schema already documents all five parameters. The description adds value by clarifying the mutual exclusivity of selectors ('Provide exactly one selector') and by explaining that runsDir is a root override for resolving loopId or latest. It also names the format enum values and the default, which reinforces the schema without repeating it verbatim.

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 tool reads a formatted evidence summary for a MartinLoop run, with specific selector options (file, loopId, latest) and format options. It distinguishes itself from martin_run_dossier by explicitly saying it is not a substitute for the full structured record, and it names the sibling tool for that purpose.

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?

The description gives explicit when-to-use guidance: 'Use after martin_run, before merge or release claims, or when sharing what happened.' It also provides a clear exclusion: 'Do not use as a substitute for missing verifier evidence; use martin_run_dossier for the full structured record.' This is strong routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this with 'Read-only' and 'not as permission to execute.' It adds context about producing a pre-work burn estimate and warns about budget/risk consent, going beyond the bare annotation flags. No contradictions with annotations.

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?

Three sentences deliver purpose, usage conditions, exclusions, and next-step guidance with zero filler. The most important information—read-only estimation—is front-loaded, and every clause earns its place.

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?

Given that annotations cover read-only and idempotent behavior, the schema covers all parameters, and an output schema exists, the description fills the remaining gaps: when to use it, what it is for, and what to do next. Nothing needed for correct invocation 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 the schema itself documents all parameters. The description adds general context about 'software objective' and 'budget/risk' but does not provide new meaning for individual parameters beyond the schema. Baseline 3 is appropriate; the description does not carry the parameter documentation burden.

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 opens with a specific verb and resource: 'Read-only cost, route, and pre-work burn estimate for a software objective.' This clearly distinguishes the tool from planning, execution, and run-management siblings like martin_plan and martin_run. It also communicates the operative scope—estimating, not executing.

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?

The description explicitly says when to use it ('before planning/preflight when a change may spend agent time or exceed budget') and when not to ('Do not use for casual questions or as permission to execute'). It also provides a concrete next step: call martin_plan if acceptable, or ask for consent for high budget/risk. This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating it 'reads saved run evidence and inspects local git signals' and 'does not modify state or contact GitHub.' It adds valuable context beyond the annotations by revealing that the tool operates on local signals only and does not reach out to GitHub, which is not inferable from structured fields alone.

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 dense but well-structured, front-loading the core purpose before usage guidance and exclusions. Every sentence earns its place: purpose, when to use, workflow placement, what not to use it for, and behavioral guarantees. It avoids fluff and provides substantial decision-relevant information in a compact form.

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?

Given that the tool has an output schema and strong annotations, the description covers the remaining context an agent needs: the domain of operation (MartinLoop run grading), the six dimensions, merge-readiness interpretation, workflow ordering, alternatives, and side-effect guarantees. The optional parameter selection is already documented in the schema, and the output schema covers return-value expectations, so no critical context 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 description coverage is 100%, so the parameters already have clear descriptions in the schema, including mutual exclusivity between file, latest, and loopId. The description itself does not add much parameter-level detail beyond saying it grades a run, but with complete schema coverage this is acceptable and does not require compensation.

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 opens with a specific verb and resource: 'Grade a MartinLoop run across six dimensions' and clearly states the output is 'a scored merge-readiness verdict.' It distinguishes the tool from siblings by explicitly listing what it is not for, such as retrieving raw verification output and reviewing PR bodies, so an agent can tell it apart without opening schemas.

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?

The description gives explicit timing guidance ('Use after a governed run completes'), workflow placement ('Use before martin_pr_summary or martin_create_pr'), and two explicit negative use cases with named alternatives (martin_get_verification_results and martin_review_pr). This leaves little ambiguity about when to invoke this tool versus its siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety and idempotency are covered. The description adds that the tool returns a 'summary with artifact directory references', which is useful but does not elaborate on what those references are or how they are structured. Given the read-only and idempotent hints, the bar is lower, and the description provides some additional context, so a 3 is appropriate.

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 a single, concise sentence that front-loads the main purpose and includes key details (attempt summary, artifact directory references, canonical run). It is efficient and readable, with no unnecessary fluff.

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?

The tool has four parameters, an output schema exists, and annotations cover safety. The description provides a high-level purpose but does not clarify which parameters are required or how they interact (e.g., the relationship between file and loopId). Given the complexity and available schema, the description is sufficient for basic understanding but not fully complete for edge cases.

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%, meaning each parameter has a description in the schema. The tool's description adds limited value beyond the schema, mainly implying that the tool focuses on a single attempt and that attemptIndex defaults to the latest. It does not explain how the parameters interplay (e.g., file versus loopId). Baseline 3 is correct because the schema already documents parameters adequately.

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 states a specific action ('Load'), a specific resource ('one Martin attempt summary'), and the key scope ('for a canonical run'). It is clear what the tool does at a high level, but it does not explicitly differentiate from sibling tools like martin_get_run or martin_get_verification_results, which also appear to retrieve run-related data.

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?

The description does not specify when to use this tool versus its siblings. For instance, it does not indicate that this tool is for inspecting a specific attempt within a run, while martin_get_run might be for whole-run details. There is no explicit guidance on which scenarios warrant this tool over alternatives, leaving the agent to infer from the name.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety and repetition behavior. The description adds that the tool returns a specific summary of fields, but it does not disclose any additional behavioral traits such as error behavior, how missing runs are handled, or constraints on parameter combinations. With annotations in place, this is an acceptable baseline.

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 a single, well-structured sentence that leads with the action and then lists the output components. Every word earns its place, and there is no redundant or vague phrasing.

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?

Given that an output schema and readOnly/idempotent annotations exist, the description adequately summarizes what the tool does and returns. However, it does not clarify that exactly one of file, latest, or loopId should be used, or whether these are mutually exclusive. This is a minor gap for a read-only retrieval tool.

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?

The input schema provides descriptions for all 4 parameters, so schema coverage is 100%. The tool description itself adds no parameter-level meaning, and the baseline of 3 is appropriate because the schema carries the burden.

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 uses a specific verb ('Load') and names the resource ('one Martin run'), then enumerates the returned fields (budget, cost, verification, artifact, canonical path summary). This makes the core purpose clear, but it does not explicitly differentiate from siblings like martin_get_attempt or martin_get_verification_results, aside from the field listing.

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?

The description gives no guidance on when to choose this tool over alternatives, nor does it mention parameter selection rules (e.g., file vs latest vs loopId). Agents are left to infer usage from the schema alone, and no exclusions or sibling comparisons are provided.

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

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

Even though annotations already mark readOnly and non-destructive, the description adds behavior beyond annotations: it reads persisted run files, does not execute commands, modify state, or contact GitHub. This is valuable operational context and does not contradict annotations.

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?

Three sentences, each earning its place: core purpose, when to use, exclusions, and behavioral boundary. The alternatives and constraints are front-loaded and the prose is tight.

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?

With a rich output schema, fully described parameters, and annotations, the description is nearly complete. It does not explicitly state that at least one of file or loopId should be supplied despite the schema listing none as required, which is a small but real invocation 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 coverage is 100%, so the input schema already documents file, loopId, and runsDir with their meaning and mutual exclusivity. The description adds no further parameter-level detail, which is acceptable because the schema carries the burden.

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 names a specific verb (Load), resource (structured verification evidence for a MartinLoop run), and content (verifier commands, pass/fail outcomes, contradiction signals). It explicitly distinguishes itself from martin_eval and martin_get_status, so an agent can tell it apart without opening schemas.

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 explicit when-to-use ('after a run completes' to confirm verifiers passed before merging/promoting) and explicit when-not-to-use with named alternatives (martin_eval for merge-readiness, martin_get_status for live status). These exclusions leave no ambiguity about routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description does not contradict those annotations, but it adds little beyond the verb 'Summarise'—no detail about what gets read, potential output size, or any other behavioral traits. This meets the baseline with annotations present.

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?

A single, front-loaded sentence with no filler: verb, object, and source are all in the first clause. It is scannable and every word earns its place.

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?

This is a low-complexity read-only tool with full annotations, an output schema, and two fully described optional parameters. The description adequately captures the operation and input source. The main gap is the lack of selection guidance among siblings, but that is less critical given how simple and safe the operation is.

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%, so the schema fully documents both parameters. The description mentions 'saved loop file or run-store directory', which mirrors the file parameter's schema description and adds no new format, syntax, or precedence information. Baseline 3 is appropriate.

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 a specific verb ('Summarise') and resource ('Martin Loop run records') plus the input source. It implies an aggregate, read-oriented operation distinct from siblings like martin_list_runs or martin_get_run, but does not explicitly differentiate itself by name, so it stops short of a perfect score.

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?

No guidance is given on when to use this tool versus the many sibling inspection tools (e.g., martin_get_run, martin_list_runs, martin_triage_runs, martin_run_dossier). The only implicit usage context is the accepted input types in the description, but there are no exclusions, conditions, or alternative routing hints.

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

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

Annotations already cover readOnlyHint and idempotentHint, so the safety profile is established. The description adds scope context ('run store', 'recent', 'lightweight filters') but discloses little beyond what the annotations and parameter schemas already imply; there is no contradiction.

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?

A single, front-loaded sentence names the operation and then summarizes the filter dimensions without any filler. Every word contributes to the agent's understanding.

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?

With no required parameters, fully described schema entries, safe annotations, and an existing output schema, the description is largely sufficient for correct invocation. It lacks only explicit alternative routing to siblings, which is more of a usage-guidance gap than a completeness 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 100%, so the baseline is 3. The description adds a useful conceptual grouping—status, lifecycle, engine metadata, and recency—that helps an agent map the seven optional filter parameters into meaningful categories beyond the flat schema entries.

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 states a specific verb ('List') and resource ('Martin runs from the run store'), making it clear this is a listing operation distinct from run/get/inspect/status siblings. It does not explicitly contrast itself with martin_triage_runs, so it falls just short of full sibling differentiation.

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?

The description implies usage: call this when you need a recent list of runs with lightweight filters, but it gives no explicit guidance about when to prefer a sibling like martin_get_run or martin_triage_runs. The context is clear enough to infer, but no exclusions or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds operational context beyond those flags: it only reads persisted run files, does not execute commands, does not modify state, and does not contact GitHub. This network-isolation and no-execution detail is valuable behavioral context not present in annotations. No contradiction.

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?

Four sentences with zero waste: core purpose, use cases, two exclusions, and a behavioral guarantee. The verb+resource is front-loaded, and every sentence earns its place.

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?

Complete for a read-only observational tool. The description covers purpose, usage context, exclusions, and behavior; the output schema explains return values; and annotations cover the safety profile. 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 description coverage is 100%, so all five parameters (file, limit, latest, loopId, runsDir) are fully documented in the schema. The description hints at the single-run scope that maps to the mutual-exclusion constraints, but it does not add parameter-level detail beyond the schema. Baseline 3 is appropriate when the schema carries the full burden.

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 states a specific verb ('Read'), a precise resource ('MartinLoop events, ledger entries, and operator control receipts'), and a scope ('for a single run'). It distinguishes itself from siblings by naming what it is not (martin_get_status, martin_get_verification_results), so an agent can select it confidently without opening schemas.

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 to use ('observe live or completed run activity, diagnose stuck or failed runs, or audit operator actions') and when not to use, naming two alternatives with the conditions that route elsewhere. Nothing is left to inference.

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

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

Annotations only declare idempotentHint=false and destructiveHint=true; the description adds the important clarification that this 'records a request and does not kill a process', which materially changes how an agent should reason about the destructive hint. It also flags the durable write. It stops short of covering permissions or repeat-call behaviour (non-idempotent → duplicate receipts?), 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?

Four sentences, front-loaded with the core action and effect, then selectors, then routing. Nothing is filler; even the semi-colon-packed selector sentence carries only required information.

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 mutating tool with an output schema (so return values need not be explained) and annotations covering the safety hints, the description covers action, effect, selectors, audit fields, and sibling routing. Only secondary details such as required permissions or behaviour on repeated calls are absent.

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 the schema already documents every parameter, including the mutual exclusivity of file/loopId/latest and the roles of runsDir, reason, and requestedBy. The description restates the selector rule and field roles rather than adding new semantics, so the baseline of 3 is appropriate.

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 opening sentence names a specific verb and resource: 'Write a durable pause receipt for one canonical MartinLoop run.' The description also distinguishes the tool from its closest siblings by naming martin_cancel and martin_continue, so an agent can route without opening any 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?

It states the positive case ('Use for a temporary hold before risky follow-up work') and the alternatives with their selecting conditions ('use martin_cancel to abandon work or martin_continue to resume'). The when-to-use / when-to-use-something-else decision is fully specified.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description reinforces the read-only nature, adds what the tool produces, and clarifies that it does not mutate files or replace the verifier. This adds useful behavioral context beyond the annotations, though idempotence is not explicitly discussed.

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?

Three sentences, with the core purpose front-loaded and no filler. Every sentence adds useful information about scope, usage boundaries, or next steps.

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?

Despite having an output schema and safety annotations, the tool is complex with 13 input parameters. The description gives a good workflow overview but does not explain how to choose or set the many constraint parameters, which are mostly undocumented at 23% schema coverage. An agent would struggle to construct a well-formed planning request.

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 only 23%, so the description must compensate for the many undocumented parameters. It mentions 'objective', 'scope', 'budget', and 'verifier', but does not map these to specific fields such as maxUsd, verificationPlan, policyPack, allowedPaths, or deniedPaths. Most parameters remain unexplained in both schema and description.

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 identifies this as a read-only planning step that converts an objective into concrete artifacts: bounded scope, verifier proposal, policy pack, and risk recommendation. It also differentiates itself from preflight and run by explicitly positioning itself before those phases.

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?

The description explicitly says when to use it ('before preflight/run' for 'authorized software changes'), when not to use it ('Do not use to mutate files or replace the verifier'), and what to do next ('call martin_preflight with the chosen scope, budget, and verifier'). This is exemplary guidance.

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

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

Annotations already cover readOnlyHint and idempotentHint, and the description adds real value beyond them: it clarifies it validates engine, verifier, path scope, and budget without spending, and sets the boundary that it is not execution or completion proof. It does not describe the reported-blocker format or failure modes, though the output schema likely carries that.

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?

Three tight sentences with zero waste: purpose front-loaded, then usage, then the next-step handoff. Every sentence earns its place.

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?

Output schema exists so return values need no explanation, and the description covers what is validated, when to call it, when not to, and what to do next. For a 17-param preflight tool this is complete enough to invoke correctly.

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 82%, above the high threshold, so the schema already documents parameters and the baseline is 3. The description groups the validated areas (engine, verifier, path scope, budget) which loosely maps to engine/verificationPlan/paths/maxUsd parameters, adding light orientation but no syntax or format detail.

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: 'Read-only validation of the exact run contract before execution or spend.' This clearly distinguishes it from siblings like martin_run (execution) and martin_estimate, and the scope (validation only, no spend) is unambiguous.

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?

Explicit when: 'Use after planning and before martin_run.' Explicit when-not: 'Do not use as execution or completion proof.' Plus routing: 'call martin_run if allowed, otherwise resolve the reported blocker.' All alternatives and conditions are named.

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

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

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint, and the description adds useful concrete context: it only reads saved run evidence, does not modify the repository, and does not contact GitHub. This goes beyond the annotations by explicitly ruling out network side effects and repo mutations.

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 main purpose is front-loaded, the alternative routing is compressed into clear usage guidance, and the no-side-effect statement earns its place. Every sentence contributes to selection, invocation, or safety clarification.

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?

With an output schema present and strong annotations, the description covers when to use it, what it consumes, what it produces, and what it does not do. An agent has enough information to invoke it correctly without guessing.

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%, so the schema already documents all five parameters, their mutual exclusivity, and format defaults. The description does not add parameter-level detail, but it does not need to since the schema covers it.

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?

Opens with a specific verb ('Generate') and names the concrete artifacts: a GitHub-ready PR title and Markdown body from a completed MartinLoop run dossier. It also distinguishes itself from martin_create_pr, martin_review_pr, and martin_eval, so an agent can tell which sibling to pick.

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 to use the tool: after a governed run completes when PR copy is needed without creating the PR. It also names the alternatives for actually opening the PR, reviewing an existing PR, and obtaining a merge-readiness grade first.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is well-covered. The description adds valuable context beyond annotations: it clarifies the tool 'only reads saved run evidence and does not modify the repository or contact GitHub,' which is a specific behavioral guarantee not present in the annotations. It also explains the behavior of omitting prBody (evaluates the auto-generated body). This adds meaningful behavioral transparency without contradicting any annotations.

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 front-loaded with the core purpose, then provides usage guidance, exclusions, and a safety note in a logical flow. Every sentence serves a distinct function—purpose, when-to-use, exclusions, and behavioral transparency—with no filler or redundancy. It is appropriately sized for the tool's complexity.

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?

Given the tool has an output schema and rich annotations, the description covers all essential aspects: it explains what the tool does, when to use it, when not to use it (with alternatives), the key parameter behavior (prBody omission), and its non-destructive nature. No critical information is missing for an agent to select and invoke this tool correctly.

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?

The input schema has 100% description coverage, so each parameter's purpose is already well-documented. The description adds minimal additional parameter semantics: it reiterates the prBody behavior (supply to review a specific body; omit to evaluate the auto-generated one) which duplicates the schema's description. No other parameters receive additional explanation in the description, so it does not exceed the baseline expected for high schema coverage.

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 states a specific verb ('Review'), a specific resource ('PR body or draft against the MartinLoop run dossier and evaluation evidence'), and a specific output ('a verdict with specific findings'). It also differentiates itself from siblings by naming martin_pr_summary and martin_create_pr as alternatives for different tasks, making the tool's distinct role unambiguous.

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?

The description explicitly states when to use this tool ('Use when you have an existing PR body and want to check whether it accurately represents the governed run evidence') and when not to use it, naming the exact alternative tools ('Do not use to generate a PR body from scratch — use martin_pr_summary instead. Do not use to open or create a PR — use martin_create_pr instead.'). This provides clear routing with no ambiguity.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds meaningful preconditions not expressed anywhere else: admission gating, matching receipts, and consent requirements around policy/budget/credentials. It stops short of spelling out that the run mutates the working tree and consumes real provider spend, but the governance framing and maxUsd/maxIterations schema fields make that inferable.

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?

Three sentences, each carrying distinct information: what it does, when to use it versus not, and what to read next. Prerequisites are front-loaded and there is no repetition of schema 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 destructive, 15-parameter execution tool with an output schema, the description supplies the workflow context (admission receipts, consent exclusions, follow-up reads) that structured fields cannot convey. The only gap is that it never states the concrete side effects — file mutation within allowedPaths and monetary spend — relying on annotations and schema to imply them.

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%, so all 15 parameters are already documented in structured fields, including the allowedPaths/deniedPaths semantics and provider fallback ordering. The description adds no parameter-level meaning beyond what the schema states, so the baseline 3 applies.

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 opens with a specific verb and resource ('Execute a governed MartinLoop coding run') and immediately scopes it with the admission condition ('after MCP workflow admission is satisfied'). The clause listing authorized task types (implementation, bug fixing, tests, refactoring) separates it cleanly from diagnostic siblings like martin_doctor or martin_estimate.

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?

Explicit when-to-use ('user has authorized implementation... and doctor/estimate/plan/preflight receipts match this task') and explicit when-not ('Do not use for question-only diagnosis or when policy, budget, credentials, or scope still need consent'). It also names the follow-up ('Next: read martin_dossier and verifier evidence'), covering the before/after sequence an agent needs.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description carries a lower burden. It adds some context about the tool reading a comprehensive dossier, but no additional behavioral traits such as return format or side effects. This is adequate but not rich.

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 three sentences with no filler: the main purpose, the selector constraint, and the usage routing. It is front-loaded with the core action and every sentence earns its place.

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 read-only tool with annotations covering safety and an output schema covering return values, the description is complete. It explains the selectors, the run-store root override, and routes to the correct sibling when the use case differs. An agent has everything needed to invoke it correctly.

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%, so the schema already documents each parameter and their mutual exclusivity. The description reiterates the selector concept and runsDir override but adds no information beyond what the schema provides. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Read the full structured execution dossier for one MartinLoop run' and enumerates the contents (attempts, events, artifacts, verification, integrity, cost, discovery surfaces). It also names siblings it is not ('use martin_get_run' and 'use martin_dossier'), clearly differentiating this tool from alternatives.

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?

Explicit when-to-use and when-not-to-use guidance is provided: 'Use for comprehensive evidence review' and 'Do not use for a compact state check; use martin_get_run, or use martin_dossier when formatted sharing output is required.' This gives the agent a decision rule, not just context.

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

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

The annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds a useful boundary beyond that: it returns only a compact budget snapshot for one run and not full events/artifacts, and clarifies that runsDir only changes the run-store root. No behavioral contradiction with the annotations.

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?

Three sentences with no filler: purpose first, selector rule second, usage boundary third. Every sentence earns its place and the most important operational constraint ('exactly one selector') is stated prominently.

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?

Given the output schema, annotations, and fully covered parameters, the description covers the remaining operational rules: exactly one selector, what each selector points to, runsDir's scoped effect, and when to route to siblings. There is no critical missing information an agent would need to invoke it correctly.

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 the baseline is 3, but the description adds semantic meaning by mapping each selector to its intended source: 'inline record' for loopJson, 'saved record' for file, 'run-store ID' for loopId, and 'newest run' for latest. It also explains the non-selector role of runsDir, which helps an agent avoid treating it as a fifth mutually exclusive option.

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 names a specific verb ('Read') and resource ('current budget, cost, remaining limits, and stop pressure for one MartinLoop run'), and proactively distinguishes from siblings by saying it is not for full events/artifacts (martin_get_run or martin_run_dossier). It is immediately clear what this tool does and what it is not.

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 a compact use case ('Use for a compact budget check') and explicit exclusions with named alternatives ('Do not use for full events or artifacts; use martin_get_run or martin_run_dossier instead'). The selector rule ('Provide exactly one selector...') also tells the agent how to choose an input path.

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

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

The description labels the operation 'read-only', which aligns with readOnlyHint and idempotentHint, and adds non-obvious selection behavior by saying only runs 'that need attention' are prioritized. It also provides the workflow cue to inspect the selected run or dossier before retrying, which is useful context beyond the annotations.

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?

Three short sentences cover purpose, usage triggers, and next step with no filler. The key selection signal, that this is for attention-worthy runs and not brand-new objectives, 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?

With readOnly and idempotent annotations, a fully described 8-parameter schema, and an output schema present, the description supplies what structured fields cannot: selection rationale and follow-up workflow. It is complete enough for an agent to decide when to invoke and what to do next.

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 each parameter has a meaningful description, including default behavior for limit and the includeHealthy filter. The tool description itself adds no parameter-level detail, which is acceptable given the high-coverage baseline.

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 states a specific resource ('saved Martin runs'), the action ('prioritization'), and the filtering criterion ('that need attention'). This clearly positions it against siblings like martin_list_runs or martin_status, which imply plain listing or status checks rather than attention-based triage.

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 concrete positive triggers ('prior attempt failed', 'asks what to fix next', 'resumes an interrupted session') and an explicit exclusion ('Do not use for a brand-new objective with no relevant run history'). It also names the next action, so an agent knows both when to call and what to do afterward.

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