scan-mcp

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

No annotations are provided, so the description carries the full burden. It does not disclose that cancellation is likely irreversible, what happens to partial scan results, whether permissions are required, or whether the job stops immediately or gracefully — critical context for a destructive operation.

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 short sentence with the action front-loaded and zero filler; it is appropriately sized but borders on under-specification rather than being padded.

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 mutation tool with no annotations and no output schema, an agent needs to know the effect of cancelling and what a successful call returns. The description supplies neither, leaving significant gaps for an irreversible operation.

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?

With one parameter at 0% schema description coverage, the description must compensate but says nothing about job_id — no format, no hint that it is likely obtained from list_jobs or start_scan_job. The schema only declares it as a bare string.

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?

Specific verb 'cancel' plus resource 'scan job' makes the operation unambiguous, and it is clearly the inverse of the sibling start_scan_job. It stops short of explicitly naming a sibling or clarifying scope (e.g., can queued jobs be cancelled or only running ones).

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 on when to call this versus letting a job finish, and no mention of prerequisites. The qualifier 'running' implies only active jobs qualify, but this is left to inference rather than 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?

With no annotations, the description carries the full behavioral burden. It implies a read-only retrieval and enumerates option categories, but does not state whether the device must exist, what happens on invalid device_id, whether any permissions are required, or what the return shape looks like.

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 a compact parenthetical that adds useful examples. There is no wasted 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 simple one-parameter tool with no output schema, the description explains the broad purpose and return categories but does not explain how to obtain device_id or what the option data will look like. It is enough to attempt a call if device_id is already known, but not fully self-contained.

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 single device_id parameter is undocumented in the schema. The description adds only 'for a specific device', not the expected format, example values, or that it should come from list_devices, leaving a meaningful gap for the only parameter.

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: 'Get SANE options for a specific device', and clarifies the kind of options with examples '(sources, resolutions, modes)'. This clearly separates it from sibling list_devices, though it does not explicitly name that sibling or state the relationship.

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 implies that the tool is used when device options are needed, but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer that device_id likely comes from list_devices and that this is a pre-scan inspection step.

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?

With no annotations, the description carries the full burden, and it does disclose the return format (JSONL) — useful information not present in the schema. However, it says nothing about event ordering, completeness, pagination/streaming behavior, or whether output is bounded, which matters for a log-fetching tool.

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 six-word sentence with the resource and scoping key front-loaded and no filler. Its terseness is efficient rather than padded, though 'JSONL' is left unelaborated.

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 no annotations, no output schema, and an undocumented parameter, the description is too thin: it does not explain what an 'event' contains, whether results are truncated or ordered, or how job_id is obtained. An agent can attempt the call but cannot predict the response.

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 0%, but the single parameter is self-explanatory by name and type. The description restates that job_id selects the job whose events are returned but adds no format details or guidance on where to obtain a job_id (e.g., from list_jobs or start_scan_job).

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 (fetch) and resource (job events, JSONL) scoped to a job_id, so an agent can tell it apart from list_jobs or get_manifest. It stops short of explicitly contrasting itself with the closest sibling, get_job_status, which also keys off a job.

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 explicit when-to-use or when-not-to-use guidance, and no mention of the alternative get_job_status for job introspection. The only signal is the implied requirement of a job_id, leaving the agent to infer the workflow.

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?

With no annotations, the description carries the full burden, yet it only says what fields are returned. It does not disclose that this is a non-mutating read, how it behaves for an unknown or expired job_id, or whether status reflects completed/cancelled 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?

A single front-loaded sentence with no wasted words. It is efficient, though the brevity is partly the source of the missing guidance rather than deliberate tightness.

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 simple one-parameter read with no output schema, the description does convey the key return contents (status and artifact counts). It still leaves the parameter's provenance and the read-only nature unexplained, which is a real but modest gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single required parameter job_id is undocumented in the schema. The description never mentions job_id, so it fails to compensate by explaining its format or that it likely comes from start_scan_job or list_jobs.

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 (get) and resource (job status) plus what is returned (artifact counts), so the agent knows this is a single-job status read rather than a list. It does not explicitly contrast with siblings like list_jobs or get_manifest, so the differentiation is inferred rather than stated.

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 on when to use this versus list_jobs, get_manifest, or get_events, and no mention of polling, terminal states, or prerequisites such as where job_id comes from. Usage is only implied by the tool 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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about error behavior for an unknown job_id, whether the manifest is cached or generated on demand, or what happens while a job is still running. It only weakly implies a read-only fetch.

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 short sentence that front-loads the verb and resource with no wasted words. It is arguably too terse rather than too long.

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 annotations, no output schema, and no parameter documentation, the description should explain what a 'manifest' contains and how it relates to other job outputs. As written it leaves the agent without enough context for a correctly-formed call in 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 0%, and the single parameter job_id is documented only insofar as the description repeats 'by job_id'. No format, provenance, or source of valid IDs is given beyond what the schema's string type already conveys.

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 (Fetch) and resource (job manifest JSON) keyed by job_id, so the operation is unambiguous. However, it does nothing to distinguish itself from siblings like get_job_status, list_jobs, or get_events, which all operate on the same job domain.

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 indication of when to use this instead of get_job_status or get_events, nor whether the manifest is available before, during, or after a scan job completes. The agent must guess the 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?

No annotations at all, so the description carries the full disclosure burden. It does add real signal with 'connected' (only currently-attached devices) and 'basic capabilities' (output is a summary, not full detail), but it says nothing about permissions, ordering, or emptiness behavior.

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?

One short sentence, front-loaded with the verb and resource, with no filler. It is arguably too terse rather than padded, but nothing wastes space.

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 parameterless read tool with no output schema, the description should clarify what a 'device' record contains or that detailed capabilities require a follow-up call. 'Basic capabilities' gestures at this but does not close the 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for.

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?

Specific verb plus resource: 'List connected scanner devices' with a stated scope 'basic capabilities'. It is distinguishable from siblings like get_device_options or start_scan_job, though it never names those siblings to sharpen the contrast.

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 only implied — an agent can infer this is the discovery step before get_device_options or start_scan_job, but the description states no when-to-use condition and explicitly excludes nothing.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read operation and discloses the inbox directory as the source, but it does not state ordering, pagination/truncation behavior, what "recent" means, or whether access permissions are required. For a listing tool with no annotation coverage, this leaves material behavioral questions unanswered.

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 wasted words. However, its brevity comes at the cost of under-specification rather than earned conciseness.

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 annotations, no output schema, and two undocumented parameters, the description should explain filtering, ordering, and what a job listing contains. It gives only a source directory and a vague recency claim, leaving the agent without enough context to invoke the tool confidently.

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%, and the description does not mention either parameter. The limit cap of 100 and the state enum (running/completed/cancelled/error/unknown) are left entirely to the schema, with no explanation of their meaning or effect. The description fails to compensate for the complete lack of parameter documentation.

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 provides a clear verb and resource ("List recent scan jobs") plus a scope ("from the inbox directory"). It implicitly distinguishes itself from siblings like start_scan_job, get_job_status, and cancel_job, though it does not explicitly name alternatives. The word "recent" is vague but the core purpose is understandable.

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 on when to use this tool versus siblings such as get_job_status or get_manifest, nor any exclusions or prerequisites. The phrase "recent" hints at a time-based context, but it is not defined or actionable. An agent must infer the use case entirely.

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?

No annotations are present, so the description carries the full burden. It does disclose one real trait — that device_id is auto-selected and other fields are defaulted when omitted — but says nothing about whether the call blocks or returns immediately, where output lands (tmp_dir), error behavior, or what identifier is returned for later polling.

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 clause with zero filler; the behavioral hint about auto-selection follows immediately. It is efficient, though the brevity arguably reflects under-specification rather than disciplined trimming.

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 an 11-parameter job-creation tool with nested objects, no annotations, and no output schema, one sentence is far too thin. An agent cannot tell from the description how to drive the duplex/source interaction, what the defaults actually are, or how to follow up on the returned job.

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 9% across 11 parameters, including two nested objects (doc_break_policy, custom_size_mm) and overlapping concepts like duplex vs. source="ADF Duplex". The description mentions omitted parameters in general and device selection, but adds no meaning about duplex, page_size, resolution_dpi, or doc-break behavior, so it does not compensate for the coverage 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 ("Start a scan job") that is clearly distinct from siblings such as get_job_status, cancel_job, and list_jobs. It stops short of explicitly contrasting with alternatives, but the purpose 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?

Implies the call is safe to make with no arguments because device selection and defaults are automatic. It never states prerequisites (e.g., use get_device_options first to override defaults) or when a different tool (get_job_status, cancel_job) is the right next step.

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