Impri

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the 5-second polling interval, the GET endpoint, what each decision value means, and that on timeout the action remains pending in the inbox. This is genuinely useful behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior, then structured decision meanings and a numbered usage flow. Every sentence carries information; 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?

An output schema exists so return shape need not be restated, and the description covers the polling model, decision semantics, timeout behavior, and follow-up routing. An agent has everything required to call and interpret this 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 parameters are already documented; the description nevertheless adds semantics, notably what timeout means (action stays pending, retry or call impri_inbox_status). It stops short of describing action_id beyond 'returned by impri_push_action'.

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 (poll/await) and resource (human decision on an action), with the exact terminal states (approved, rejected, timeout). It is clearly distinguishable from siblings like impri_push_action and impri_inbox_status.

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?

Explains when to use it via an explicit 3-step flow (push_action → await_decision → report_result) and names the alternative on timeout (impri_inbox_status, plus considering pausing submissions). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, and the description adds substantial behavior beyond them: scheduled runs with jitter, URL/content-hash deduplication, delivery of only new matches, and the baseline-on-first-run rule that suppresses the initial alert burst. That baseline/dedup disclosure is the kind of non-obvious behavior an agent cannot get from 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?

Front-loaded with the core purpose, then behavior, then a worked example that earns its space given the nested spec. Slightly long, but every block adds information rather than restating the 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?

An output schema exists and the description briefly enumerates the return fields, so return values are covered. For a nested-spec creation tool the description plus SPEC.md reference is sufficient, though it leaves the preset-sibling distinction unaddressed.

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%, but the single 'spec' parameter is a nested object pointing to SPEC.md §3.2, so the schema alone is thin. The description compensates with a concrete example enumerating name, kind, config, keywords, keywords_none, min_score, and schedule, plus a worked min_score/jitter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a watcher') and immediately scopes what it monitors (RSS feeds, Reddit, URL diffs) and where it delivers. It does not, however, distinguish itself from the sibling impri_create_watcher_from_preset, which an agent must disambiguate on its own.

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 conveys context (scheduled monitoring to inbox/webhook) but never states when to choose this over impri_create_watcher_from_preset or other siblings. Usage is implied by the example rather than declared, leaving the main routing decision to inference.

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

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

Annotations already declare non-read-only, non-idempotent, open-world and non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond them: presets perform URL building, keyword setup and SSRF validation; name and schedule default to preset values; and the return shape is stated. It does not mention permission requirements or error behavior, keeping it out of the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the preset-responsibility rationale, then defaults, then return shape, then examples. Every sentence earns its place, though four examples is on the generous side for a tool with only four parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still names the returned fields briefly, and it correctly delegates the open-ended param vocabulary to impri_list_watcher_presets rather than trying to enumerate every preset inline. For a nested-object tool whose param keys are preset-dependent, this is as complete as a description can reasonably be.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that params keys come from the preset listing tool, that schedule is an override of a preset default, and that name defaults to "{preset title}: {primary param value}". The examples show preset-specific param keys (subreddit, owner/repo, keyword/min_points) that the schema's free-form additionalProperties cannot convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (create a watcher from a preset template) and immediately distinguishes this path from raw watcher construction by explaining that presets handle all config building. It also points at the companion tool impri_list_watcher_presets as the source of valid ids and params, so an agent can separate it from impri_create_watcher.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: supply preset_id plus param values obtained from impri_list_watcher_presets, with defaults applied when name/schedule are omitted. Four worked examples show concrete invocation patterns. It never explicitly states when to prefer this over the sibling impri_create_watcher, so it falls short of the top band.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context — that pending actions can expire before review — and a pacing recommendation, though it says nothing about auth or rate limits.

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 tight sentences, front-loaded with the purpose and followed by the actionable trigger condition. Every clause earns its place with no repetition of the title or annotations.

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, read-only status tool with an output schema and full annotation coverage, the description supplies all that is missing: what is returned and the decision it should drive. Nothing an agent needs to invoke it correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description correctly refrains from inventing parameter guidance.

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 — checking how many actions await human decisions — and specifies the return payload (pending count plus pending action titles). This clearly separates it from siblings like impri_push_action and impri_await_decision, which write or block rather than report status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit operational context: call this before starting a large batch, and pause if the inbox is backed up. It implies the when-not case (backlog → don't proceed) but does not name any alternative tool for a different 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, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description still adds useful substance by enumerating the shape of each preset (id, human-readable title, required and optional params, default schedule), which is real behavioral context beyond the annotations, though nothing about ordering guarantees or caching is mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then the definition, then the usage instruction, then an illustrative example. Every block earns its place, though the multi-line example output is somewhat verbose given an output schema already exists.

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 read tool with a complete output schema and full annotation coverage, the description supplies everything needed: what presets are, their field composition, and how to chain into impri_create_watcher_from_preset. No material gap remains for an agent deciding whether and how to call it.

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 of 4 applies. The description correctly explains that no param values are needed at this stage and that params belong to the downstream creation call, which is relevant clarifying context despite there being no schema to complement.

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 ('List all available watcher presets') and immediately clarifies the resource type ('pre-configured watcher templates for common sources'). An agent can distinguish this from the sibling impri_list_watchers because the description defines presets as templates with id/title/params/schedule.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Call this first to discover which preset fits your monitoring goal, then use impri_create_watcher_from_preset', giving both the ordering and the named follow-up tool. It also states the payoff ('No deep knowledge of watcher config schemas is needed'), removing ambiguity about when this is preferable to building a watcher manually.

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 non-destructive behavior, so safety is covered. The description adds useful context about what the read surface looks like (count plus per-watcher summary) and points at the 'degraded' state as a thing worth auditing, which is not stated in the schema.

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, front-loaded with the action and scope, then the use cases and return shape. No filler, no repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained in prose, and annotations carry the safety profile. The description still supplies purpose, filtering behavior, and concrete usage scenarios — nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented with its enum and the omit-to-return-all semantics. The description only restates the optional status filter, adding no format or behavior detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all configured watchers') plus the scoping option (status filter). The word 'configured' implicitly separates it from the sibling impri_list_watcher_presets, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives three concrete use cases: auditing monitoring coverage, checking for degraded watchers, and finding a watcher_id for follow-up calls. That is strong positive guidance, but there is no explicit when-not or named alternative (e.g., use list_watcher_presets for templates).

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

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

Annotations only declare the write/no-idempotency/no-destruction safety profile, so the description carries the behavioral burden and does it well: reviewer-facing card composition, the fact that editable fields are echoed back, the pending status contract, and an explicit instruction to persist action_id for follow-up calls. This is context an agent cannot infer from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose, then workflow, then return contract, then a concrete example — a sensible information hierarchy with no filler sentences. The Reddit example is somewhat long relative to the rest, but it earns its space by demonstrating the optional/editable fields concretely.

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 parameters, nested objects, full schema coverage and an output schema, the only remaining agent questions are the workflow and follow-up path — both are answered, including the sibling poll and the need to retain action_id. Nothing material 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 already 100%, so baseline is 3. The worked example adds meaning beyond the schema by showing how kind, title, preview, target_url, and editable combine in a realistic call, and by demonstrating the dot-notation value for editable. It doesn't add format constraints the schema lacks, so it lands just above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Submit an action to the Impri human-approval inbox") and immediately frames the workflow, which an agent can distinguish from siblings like impri_report_result or impri_create_watcher. The example reinforces the resource shape. No ambiguity about what gets created.

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?

Explains the workflow context (operator approves/rejects, you poll for the decision) and explicitly routes the agent to impri_await_decision for the follow-up step, which is real alternative-routing value. It stops short of any when-not guidance or prerequisites (auth, rate limits), so it is clear context rather than a complete decision rule.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses the concrete side effect: the operator sees 'executed' or 'execute_failed' in the inbox next to the original action and decision. It does not discuss retry/idempotency behavior when called twice, which is the only notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then the workflow consequence, then the always-call rule, then a clean enum breakdown. Every sentence earns its place 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 small reporting tool with an output schema and full annotation coverage, this description supplies everything an agent needs: role in the workflow, mandatory usage, and the semantics of both status values.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what each status value means and instructing the agent to put the error in detail on failure, adding meaning beyond the enum list.

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 (report) and resource (the result of an approved action), and the workflow framing ('closes the audit loop') tells the agent exactly what this does. It is unambiguous against siblings like impri_push_action and impri_await_decision.

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?

'Always call this after attempting an approved action, even on failure' gives explicit, actionable timing guidance for a step that is easy to forget. There are no named alternatives or exclusions, but the trigger condition is stated clearly and directly.

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