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 cover readOnly, idempotent, and non-destructive behavior. The description adds useful context by clarifying that the tool reads 'persisted evidence' and that omitting loopId dynamically loads the latest run. The closing sentence reinforces the read-only guarantee, though it is somewhat redundant 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?

The description is four sentences with no filler. It front-loads the core purpose, then covers parameter behavior, usage boundaries, and read-only safety, with every sentence earning 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 a single optional parameter, an output schema, and annotations covering safety, the description is complete. It provides purpose, usage constraints, alternatives, parameter guidance, and state-change guarantees, so an agent can select and invoke the 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?

Schema description coverage is 100% and the schema already documents loopId as optional with the 'omit to read latest run' behavior. The description restates this logic but adds no new semantic detail beyond the input 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 uses a specific verb ('Read'), names a precise resource ('read-only evidence projection used by the Arcade view'), and explicitly distinguishes itself from sibling tools like martin_status and martin_run_dossier. An agent can immediately understand what this tool does and how it differs 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?

The description states 'Use only for Arcade rendering' and explicitly redirects to martin_status for budget pressure and martin_run_dossier for full evidence. It also explains the loopId behavior clearly: provide it for an exact run or omit it for the latest 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 mark destructiveHint=true and idempotentHint=false. The description adds behavioral nuance beyond that by clarifying that the tool 'records a request and does not kill a process' and that the receipt is 'durable.' It does not fully spell out what state changes the cancellation causes, but it meaningfully reduces ambiguity around process termination.

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, all front-loaded and purposeful. The core action and primary constraint come first, followed by usage conditions and the key alternative. No filler or repetition of schema details.

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 exists, return values need not be described. The description covers when to use it, when not to, how selectors work, the side-effect boundary, and the audit parameters. Nothing essential is missing for an agent to select and invoke the 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by grouping parameters semantically: it states the exact-one-selector requirement among file, loopId, and latest, explains runsDir as a run-store root override, and identifies reason and requestedBy as audit context. This goes beyond the schema's per-property text.

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-resource pair: 'Write a durable cancellation receipt for one canonical MartinLoop run.' It clearly defines scope ('one... run') and differentiates the tool by noting it records a request rather than killing a process, which separates it from siblings like martin_pause.

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 usage guidance is provided: 'Use when work must be abandoned, not temporarily held' and 'use martin_pause for a reversible hold.' This gives an agent a clear decision rule and names the alternative tool for the opposite case.

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 adds the behavioral context of 'durable' persistence and the post-pause/checkpoint timing, which is useful beyond the annotations. However, with destructiveHint=true, it does not explain what destructive effect may occur or why a record-request operation is flagged destructive, leaving that significant behavior unexplained.

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, focused sentence with no filler. It front-loads the core action and provides the key contextual condition without wasting words.

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 six parameters, a oneOf selection requirement, and zero parameter descriptions, the tool needs much more contextual explanation to be invoked correctly. The description tells why and when, but not how to specify the target run or what values like reason, runsDir, and requestedBy mean. The output schema exists but does not compensate for the missing parameter semantics.

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 carries full responsibility for explaining parameters, but it mentions none of them. The oneOf construct with file, loopId, or latest is present in the schema but not elaborated, leaving the agent to guess what each identifier means and when to choose one.

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 ('Record') and clearly identifies both the action (durable continue/resume request) and the context (a Martin run after a human pause or approval checkpoint). This is distinct from sibling tools like martin_pause or martin_cancel, as it describes resumption rather than stopping.

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 phrase 'after a human pause or approval checkpoint' gives useful contextual guidance for when the tool should be invoked. It does not explicitly name alternatives or say when not to use it, so it falls short of full exclusionary guidance, but the timing context is clear.

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 indicate destructiveHint=true, and the description adds meaningful context by explaining that the destructive action only happens when execute=true. This clarifies the side-effect boundary and prevents accidental PR creation.

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 compact sentences, with the primary action and the critical execute flag front-loaded. Every sentence adds operational value and there is no filler.

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 8 parameters, a oneOf constraint, and no schema descriptions, this description is far too thin. It omits how to choose among file, loopId, or latest, what format options mean, and how base, title, and runsDir affect the PR. The output schema may cover return values, but the input semantics are largely undocumented.

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, but it only explains execute. The remaining seven parameters (file, loopId, latest, format, title, base, runsDir) and the oneOf selection logic are left unexplained, leaving agents to guess how to specify the dossier source.

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 and resource: create or preview a GitHub PR with a MartinLoop dossier body. The preview-vs-execute distinction is clear, though it does not explicitly differentiate it from sibling PR-related tools like martin_pr_summary or martin_review_pr.

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 provides clear usage guidance for the key behavior: use execute=true to actually call gh, otherwise preview. It does not mention alternatives or when-not-to-use, but the preview/execute gate is a strong, explicit usage signal.

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' aligns with them. The description adds useful context by scoping the diagnostic coverage and warning that its output must not be treated as task-completion proof.

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 four short sentences with the core purpose front-loaded. Every sentence contributes either purpose, usage timing, an exclusion, or next-step routing, with no repetition of schema or annotation 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 read-only, idempotent, zero-required-parameter diagnostic tool with an output schema, the description fully covers what it inspects, when to use it, what it should not be used for, and the follow-up routing. An agent has what it needs to select and invoke the 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?

All three parameters have full schema descriptions, so schema coverage is 100%. The tool description does not add parameter-specific detail, which is acceptable because the structured schema already carries that 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 'Read-only environment, engine, workspace, and run-store diagnostics for MartinLoop', which clearly names the resource scope and the action. It further differentiates the tool as a universal first-step check ('Use first...') among many sibling 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?

It explicitly states when to use the tool: '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') and routes to the next relevant tool based on the situation.

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' is consistent. It adds useful behavioral context: the summary is formatted, a selector must be supplied, format defaults to json, and the output is meant to serve as a handoff receipt. This goes beyond the annotations without contradicting them.

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 with the core purpose, followed by parameter rules, usage context, and alternatives. The 'Next: review verification results, retry, or hand off the receipt' sentence is slightly vague but adds workflow context without bloating the text.

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 5-parameter read-only tool with 100% schema coverage, an output schema, and readOnly/idempotent annotations, the description covers everything needed: what it reads, how to select a run, format handling, runsDir override, workflow timing, and the sibling alternative. No critical operational detail 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 schema already fully documents file, loopId, latest, format, and runsDir. The description repeats the selector exclusivity and the format options rather than adding new semantic depth. This meets the baseline but does not substantially elevate parameter understanding.

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 a formatted evidence summary for one MartinLoop run.' It also clearly distinguishes itself from the sibling martin_run_dossier by calling that the 'full structured record,' so an agent can select between them without inspecting 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 when-to-use guidance: 'Use after martin_run, before merge or release claims, or when sharing what happened.' It also provides an explicit 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, idempotentHint, and destructiveHint, and the description adds valuable behavioral context beyond those: it 'reads saved run evidence and inspects local git signals' and explicitly states 'it does not modify state or contact GitHub.' This clarifies the data sources and side-effect boundary without contradicting 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 sequencing guidance, exclusions, and behavioral guarantees in a compact, structured way. Every sentence adds information needed for correct selection and invocation; the length is justified by the many sibling tools and the need to route to alternatives.

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 a rich output schema, so return-value details are covered separately. The description supplies everything else an agent needs: when to call it, when not to call it, what it reads, what it does not affect, and how it fits into the merge workflow. No important gap remains.

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 the file, loopId, latest, and runsDir parameters and their mutual exclusivity. The tool description focuses on the tool's purpose rather than parameter details, which is acceptable because the schema already carries the parameter semantics.

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 ('Grade') and resource ('a MartinLoop run'), enumerates the six evaluation dimensions, and names the output ('scored merge-readiness verdict'). It also differentiates itself from sibling tools like martin_get_verification_results and martin_review_pr, making its purpose 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 says to use it after a governed run completes and before martin_pr_summary or martin_create_pr, establishing clear sequencing. It also gives two concrete negative cases with named alternatives: raw verification output goes to martin_get_verification_results, and existing PR review goes to martin_review_pr.

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, covering the safety profile. The description adds context that the result is a summary with artifact directory references, but it does not clarify canonical-run semantics or attempt-selection behavior beyond what the schema already states.

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 tightly written sentence that front-loads the action and object with no filler. Every word earns its place; the only ambiguity, 'canonical run,' is a semantic issue rather than a conciseness problem.

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 rich input schema, output schema, and readOnly/idempotent annotations compensate for much of the brevity. The remaining gaps are selection guidance versus sibling tools and a definition of 'canonical run,' making the description adequate but not fully complete.

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 four parameters are already documented in the input schema. The description adds no additional meaning about choosing between file and loopId, runsDir, or attemptIndex, so the baseline score 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 description uses a specific verb ('Load') and a specific resource ('one Martin attempt summary') plus a distinctive qualifier about artifact directory references. It clearly differentiates from run-level tools like get_run, though 'canonical run' remains undefined and no sibling is explicitly named.

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?

Usage is implied rather than stated: the tool is for loading attempt summaries from canonical runs, with schema defaults indicating attemptIndex selects the latest attempt. It does not say when to prefer this over get_run, inspect, or run_dossier, nor what disqualifies a non-canonical 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 readOnlyHint and idempotentHint, so the safety profile is known. The description adds useful context about the returned summary content, but does not disclose operational details such as identifier resolution behavior, run-store defaulting, or any edge cases beyond what annotations and schema already convey.

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 one efficient sentence with no wasted words. It front-loads the core action ('Load one Martin run') and then lists the returned summary categories, making it easy to scan and undersstand.

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 input schema, a covering output schema, and read-only/idempotent annotations, the description is largely complete for a single-run read tool. It lacks usage-routing context and does not explain how the identifier options relate, but those gaps are partly covered by the schema's oneOf structure and sibling names.

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 each parameter (file, latest, loopId, runsDir) is already documented. The description adds no additional parameter-level semantics beyond 'canonical path' alignment, and the oneOf-selection logic is left entirely to the 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 states a specific verb ('Load'), a specific resource ('one Martin run'), and a concrete set of returned summary categories (budget, cost, verification, artifact, canonical path). This clearly distinguishes it from list-oriented tools like martin_list_runs and attempt-level tools like martin_get_attempt.

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?

There is no guidance about when to prefer this tool over siblings such as martin_get_attempt, martin_status, or martin_dossier. The description implies the general need to load a run but gives no exclusions, prerequisites, or alternative-selection advice.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces and expands on this by stating the tool 'only reads persisted run files and does not execute commands, modify state, or contact GitHub.' This adds concrete behavioral 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?

Four sentences, each with a distinct job: what the tool returns, when to use it, which alternatives to use instead, and what side effects it does not have. There is no filler or restatement of the tool name.

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 multiple identifier modes, an output schema, and many sibling tools, but the description plus schema together cover the input modes, return content, routing, and safety profile. Nothing needed to call 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 the schema already documents file, loopId, and runsDir, including their mutual exclusivity. The description does not add extra guidance on how to choose between file and loopId, but the baseline of 3 is appropriate because the schema carries the semantic load.

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: 'Load structured verification evidence for a MartinLoop run', and enumerates the contents: verifier commands, pass/fail outcomes, and contradiction signals. It also distinguishes itself from martin_eval and martin_get_status, making the tool's role unmistakable.

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 explicitly states when to use the tool ('Use after a run completes to confirm whether automated verifiers passed before merging or promoting the result') and gives two explicit negative-routing instructions with named alternatives: martin_eval for merge-readiness grades and martin_get_status for live run status. 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 declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral value by specifying that the tool summarises records rather than returning them raw, and that it works from a saved loop file or run-store directory. This is consistent with the annotations and adds context beyond them.

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, front-loaded sentence with no filler. Every word contributes to explaining the action and the accepted inputs.

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 zero required parameters, a complete output schema, and annotations covering idempotency, the description is largely sufficient. The main missing element is routing guidance among sibling tools, but that is more of a usage-guideline concern; the core invocation context is adequately covered.

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 both parameters are already well described in the schema. The tool description does not add parameter-level meaning beyond what the schema provides, so the baseline score 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 description uses a specific verb, 'Summarise', and identifies the resource, 'Martin Loop run records', plus the two accepted input source types. It is clear about what the tool does, though it does not explicitly differentiate itself from sibling tools such as martin_get_run, martin_status, or martin_run_dossier.

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 provided about when to use this tool instead of the many sibling inspection/status tools. There are no exclusions, conditions, or references to alternatives, leaving the selection decision entirely to the agent.

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, so the safety profile is covered. The description adds that results are recent runs from the run store and that filters are lightweight, but it does not detail ordering, default recency behavior, or pagination.

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 sentence, front-loaded with the action and resource, then filter categories. There is no filler or redundant repetition of schema details.

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 list tool with 100% schema coverage and an output schema, the description is nearly sufficient. It lacks explicit guidance on when to prefer this over sibling run-inspection tools, but all required call parameters are covered by the schema and annotations carry the safety profile.

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 seven parameters are individually documented. The description adds a useful grouping (status, lifecycle, engine metadata, recency) but no additional syntax, allowed values, or relationships beyond what the schema already provides.

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 the specific verb 'List' with the resource 'Martin runs' and further scopes it to the run store with 'recent' and 'lightweight filters.' This clearly distinguishes it from siblings like martin_get_run, martin_inspect, and martin_status, which target single runs or different views.

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 this is the lightweight listing tool, but it never explicitly states when to choose it over martin_get_run, martin_inspect, or martin_triage_runs. No exclusion criteria or alternative routing is provided, so usage guidance is only implicit.

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 mark the tool readOnly, idempotent, and non-destructive. The description adds meaningful specifics: it only reads persisted run files, executes no commands, modifies no state, and does not contact GitHub. This goes beyond the annotation hints and prevents incorrect assumptions.

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 four sentences with no filler: purpose first, usage and exclusions next, behavioral guarantees last. Every sentence earns its place and the most important scoping 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?

With full parameter documentation, an output schema, and read-only annotations, the description closes the remaining gaps: what data is exposed, when to use it, when not to use it, and what side effects it avoids. An agent has enough context 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?

Schema description coverage is 100%, and each parameter already has a meaningful description including mutual-exclusion constraints and defaults. The tool description adds no parameter-specific detail, but none is necessary because 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 names a specific resource (MartinLoop events, ledger entries, operator control receipts) and a specific action (read). It also explicitly separates itself from status-checking and verification-evidence tools, so an agent can distinguish it from the sibling tools 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 explicitly states when to use the tool (observe, diagnose, audit) and gives clear exclusions with alternative tools. Minor deduction: it references 'martin_get_status', but the sibling tool list contains 'martin_status', not 'martin_get_status', so the alternative pointer is slightly unreliable.

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 convey idempotentHint=false and destructiveHint=true, so the bar is lower. The description adds useful context by clarifying that the tool 'records a request and does not kill a process' and that the receipt is durable. However, it does not explain what destructive side effect the destructiveHint refers to, such as overwriting prior pause state or mutating the run record, so the behavioral disclosure remains incomplete.

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 sentences with no filler. The core verb-resource pair is front-loaded, selector requirements follow immediately, and the guidance about when not to use it is packed into the final clause. 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 six-parameter tool with a oneOf constraint and existing annotations, the description covers the selector rule, optional parameter purposes, the intended use case, and how this tool differs from its closest alternatives. The output schema exists, so return-value details do not need to be repeated in prose.

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 all six parameters. The description adds value by grouping file, loopId, and latest as mutually exclusive selectors and by summarizing runsDir as the run-store root and reason/requestedBy as audit context, but this mostly restates or lightly repackages schema information rather than adding deep new 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?

The description opens with a specific action and resource: 'Write a durable pause receipt for one canonical MartinLoop run.' It clearly distinguishes this from related tools by naming martin_cancel and martin_continue, and it frames the operation as a temporary hold rather than termination.

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 for a temporary hold before risky follow-up work.' It also gives exclusions and alternatives: 'This records a request and does not kill a process; use martin_cancel to abandon work or martin_continue to resume.' An agent can confidently choose between pause, cancel, and continue.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that by specifying exactly what the validation covers (engine, verifier, path scope, budget) and clarifying it is not a proof of execution or completion. This enriches the behavioral contract without contradicting 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?

Two sentences deliver the purpose, usage timing, checks performed, exclusion, and next step. Every clause earns its place, and the most critical info (purpose) is front-loaded. There is no fluff or 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?

For a preflight validation tool with 17 parameters, an output schema, and read-only/idempotent annotations, the description fully covers the needed context: what it validates, when to call it, what it is not, and what to do next. The output schema handles return specifics, so no additional return-value explanation is needed. An agent can invoke this tool correctly with no missing information.

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%, and most parameters have clear descriptions (e.g., engine enum, maxUsd, maxTokens, deniedPaths). The description does not add parameter-specific details beyond what the schema already provides. With high coverage, the description is not required to elaborate on each parameter, so a baseline score 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 description states a specific action ('Read-only validation of the exact run contract') on a specific resource (the run contract) and explicitly distinguishes it from execution by noting 'before execution or spend' and naming the sibling martin_run. It also makes clear it is not a proof of completion, removing any ambiguity about its role.

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 ('Use after planning and before martin_run'), states the checks it performs (engine, verifier, path scope, budget), and directs the next action ('call martin_run if allowed, otherwise resolve the reported blocker'). It also says 'Do not use as execution or completion proof,' which is a clear when-not-to-use condition. No exclusions or alternatives are left unstated.

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, and the description adds meaningful context by stating the tool 'only reads saved run evidence and does not modify the repository or contact GitHub.' This clarifies that despite producing GitHub-ready copy, it has no external side effects. No contradiction 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?

The description is front-loaded with the core action and then efficiently covers usage timing, sibling alternatives, preconditions, and behavioral safety. Every sentence earns its place, and there is no redundant restating of the tool name or schema details.

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 strong annotations, full parameter schema coverage, and the presence of an output schema, the description is complete enough for correct tool selection and invocation. It explains when to use it, what it consumes, what it produces, how it differs from related tools, and that it is read-only with no GitHub interaction.

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, including the oneOf requirement among file, loopId, and latest, and the format enum. The description adds no parameter-specific semantics, which is acceptable because the structured 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 opens with a specific verb and resource: 'Generate a GitHub-ready pull-request title and Markdown body from a completed MartinLoop run dossier.' It clearly states the deliverable, including verification grade and score, and distinguishes itself from PR-creating and PR-reviewing siblings without needing to infer from the name alone.

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 a governed run completes when you need PR copy without creating the PR') and names concrete alternatives with conditions: use martin_create_pr to open the PR, martin_review_pr for existing PR bodies, and martin_eval first if a merge-readiness grade is needed. This fully routes an agent to the right sibling.

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. The description adds genuinely useful context beyond those fields: the tool 'only reads saved run evidence and does not modify the repository or contact GitHub.' This is valuable because the name 'review_pr' could otherwise imply GitHub API interaction. No contradiction 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?

Five sentences, each earning its place: purpose, when-to-use, invocation mode, two sibling exclusions, and safety. It is appropriately sized given the sibling ambiguity (martin_pr_summary, martin_create_pr) and includes all necessary routing information. The prBody sentence slightly overlaps with schema text, which keeps it from a 5.

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 6-parameter tool with full schema coverage and an output schema, the description covers everything an agent needs: what it does, when to use it, how to invoke both modes, which tools not to use instead, and the safety profile. Return-value details are handled by the output schema, so no gap remains.

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's guidance on prBody ('Supply prBody to review a specific body string; omit it to evaluate the auto-generated dossier body') largely restates the schema's own prBody description. It adds minimal meaning beyond the structured fields, but no compensation is needed given full 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') with a clear resource ('PR body or draft against the MartinLoop run dossier and evaluation evidence') and a concrete outcome ('return a verdict with specific findings'). It further disambiguates from siblings by naming what it is not: not martin_pr_summary (generation) and not martin_create_pr (creating/opening PRs). An agent can select this tool confidently 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?

Explicit when-to-use is stated ('when you have an existing PR body and want to check whether it accurately represents the governed run evidence') and two explicit exclusions name the exact alternatives. The description also covers the two invocation modes (supply prBody vs omit it), which is practical operational guidance an agent needs before calling.

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 destructiveHint=true and idempotentHint=false, so the description doesn't need to restate that this mutates state. It adds useful behavioral context about the governance workflow ('after MCP workflow admission is satisfied', receipts matching, next step to read dossier/verifier evidence). This goes beyond annotations without contradicting them.

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: what the tool does, when to use it, when not to use it, and what to do next. The purpose is front-loaded, and each sentence earns its place. It is concise without losing necessary governance context.

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's high complexity (14 parameters, output schema present, many siblings), the description covers the key non-schema context: authorization requirements, workflow prerequisites, exclusions, and the next recommended action. The output schema handles return-value documentation, so nothing essential is missing 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 100%, so all 14 parameters are already individually documented in the input schema. The description adds no parameter-specific meaning beyond what the schema provides, which matches the baseline of 3 for high schema coverage. No compensation is needed.

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+resource: 'Execute a governed MartinLoop coding run.' It further distinguishes the tool by listing concrete supported task types ('implementation, bug fixing, tests, or refactoring') and by referencing the prior workflow stages (doctor/estimate/plan/preflight), making it clearly distinct from siblings such as martin_plan, martin_status, or martin_list_runs.

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 conditions: the user has authorized implementation/bug fixing/tests/refactoring and the upstream receipts match the task. It also gives explicit when-not-to-use exclusions: 'Do not use for question-only diagnosis or when policy, budget, credentials, or scope still need consent.' This is strong routing guidance relative to the many sibling tools.

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, so the safety profile is covered. The description adds meaningful behavioral context by specifying that the tool reads a full dossier, requires exactly one selector, that runsDir changes the run-store root, and that it is not a formatted-output tool. No contradiction 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 purposeful sentences with no filler. The main purpose is front-loaded, followed by selector usage and then exclusion guidance. Every sentence contributes actionable 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 read-only, idempotent tool with full schema coverage and an output schema, the description is complete. It covers purpose, selector constraints, runsDir semantics, and alternative tools, leaving no critical calling decision ambiguous.

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 already 3. The description goes beyond the schema by stating the exclusivity requirement ('exactly one selector') and clarifying runsDir's role ('changes the run-store root'), adding value on top of the already well-described parameters.

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?

Uses a specific verb ('Read') with a clearly defined resource: 'the full structured execution dossier for one MartinLoop run.' It enumerates the dossier contents (attempts, events, artifacts, verification, integrity, cost, discovery surfaces) and explicitly contrasts itself with martin_get_run and martin_dossier, making sibling differentiation easy.

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?

States exactly when to use it ('comprehensive evidence review') and when not to ('compact state check'), naming the alternatives explicitly: martin_get_run for compact state and martin_dossier for formatted sharing output. It also gives selector usage guidance ('exactly one selector: file, loopId, or latest').

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, so the safety profile is covered. The description adds useful behavioral boundaries: it returns budget/cost/limits/stop pressure only, is scoped to one run, and does not provide full events or artifacts. It also clarifies that runsDir only changes the run-store root, preventing misinterpretation of side effects.

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: purpose first, selector guidance second, usage boundaries last. Every sentence earns its place, and there is no redundant repetition of schema details.

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 oneOf selector structure, 5 parameters, and presence of an output schema, the description covers all needed context: what is returned, how to select the target run, the optional runsDir behavior, and when to choose sibling tools. Nothing essential 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%, with each parameter already described, including mutual exclusivity. The description adds little beyond rephrasing the selector categories and the runsDir scope, which the schema already conveys. Baseline 3 is appropriate because the schema does the heavy lifting.

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 clear verb and resource: 'Read the current budget, cost, remaining limits, and stop pressure for one MartinLoop run.' It also distinguishes itself from siblings by explicitly saying it is a compact budget check and not for full events or artifacts, naming martin_get_run and martin_run_dossier as 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?

It states when to use the tool ('Use for a compact budget check') and when not to use it ('Do not use for full events or artifacts'), with explicit sibling alternatives. It also constrains selector usage with 'Provide exactly one selector,' which is actionable 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 establish readOnlyHint and idempotentHint, so the description does not need to repeat them. It adds value beyond annotations by clarifying that this surfaces attention-worthy runs by default and that healthy runs are excluded unless includeHealthy is true, plus the workflow hint to inspect before retrying.

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 short sentences, with the purpose in the first sentence and all subsequent sentences earning their place: trigger conditions, an exclusion, and a next-step directive. There is no redundancy or filler.

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 8 optional params, full schema coverage, an output schema present, and read-only/idempotent annotations, the description supplies the missing selection context: when to call it, when not to, and what to do next. Nothing needed for correct selection or 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 description coverage is 100%, and every parameter has its own description. The tool description adds no parameter-level detail, but the baseline of 3 applies because the schema carries the semantic weight.

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 action, resource, and filtering criterion: 'Read-only prioritization of saved Martin runs that need attention.' This distinguishes it from sibling tools like martin_list_runs or martin_status, which list or report status without prioritization. The 'need attention' scope is precise.

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 names concrete triggering scenarios: prior attempt failed, user asks what to fix next, or resuming an interrupted session. It also gives an explicit non-use case: brand-new objective with no relevant run history, and ends with the correct next action, inspect the selected run or dossier before retrying.

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