Refix

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

Annotations already declare destructiveHint=true and idempotentHint=true, so 'safe to call more than once' largely restates structured data. The one real addition is the word 'Request,' implying cancellation may be queued rather than immediate. However, for a destructive operation the description never says what is destroyed or what state the investigation is left in, which is the main behavioral 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?

Two short sentences, action first and the safety caveat second. Nothing is padded and nothing repeats the title verbatim beyond what is needed to state scope.

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, and annotations cover the safety profile. What remains missing is what happens after the request (does cancellation take effect immediately, can it be reverted, what happens to in-flight findings), which matters for a destructive 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?

Schema coverage is 50%: idempotency_key is well documented in the schema, but investigation_id has no description anywhere. The tool description mentions neither parameter, so it does not compensate for the undocumented half, leaving the format and source of investigation_id entirely implicit.

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: 'Request cancellation of a running investigation.' The verb 'request' signals this may be asynchronous rather than an immediate cancel, which is a meaningful distinction. No sibling in the list performs cancellation, so no explicit differentiation is needed, but the description never clarifies what a 'running' investigation is versus other states.

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 only guidance offered is 'Safe to call more than once,' which is an idempotency trait, not a when-to-use rule. There is no mention of prerequisites (must the caller own the investigation?), when cancellation is appropriate versus letting an investigation finish, or what to do if it already completed.

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?

Adds real context beyond annotations: watchers consume the workspace's Refix usage, are visible to everyone in the workspace, and the agent is instructed to disclose both. The alerts routing behavior (mcp_assistant keeps alerts in Refix for refix_list_findings, with no Slack post or email) is also disclosed. Minor gap: it doesn't say whether the watcher starts running immediately or what the creation response contains, though an output schema exists.

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 dedupe instruction is front-loaded and every sentence carries information. It is dense and the alerts clause is a long semicolon chain, but nothing is redundant with the schema 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 mutation tool with annotations (readOnlyHint false, idempotentHint true, destructiveHint false) and an output schema, this covers preconditions, side effects on usage and visibility, and alert delivery. What remains unsaid — return shape and immediate execution behavior — is carried by the output schema and annotations.

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 75% and already documents timezone, objective, and idempotency_key, so the baseline is 3. The description goes beyond that by explaining what each alerts value implies operationally ('mcp_assistant' keeps alerts in Refix for refix_list_findings; 'slack'/'email' must match alert_channel from refix_get_context), which the enum alone does not 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 Refix watcher") and then defines what a watcher actually is: something that carries a goal, keeps working against connected data, and reports findings to a chosen place. That definition, plus "ongoing goals, not one-off questions," lets an agent separate it from refix_investigate and refix_update_watcher 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?

Gives an explicit precondition ("Call refix_list_watchers first and do not create a duplicate") and a clear when-to-use rule (ongoing goals, not one-off questions). It doesn't name the alternative tool for one-off questions by name, so the routing to refix_investigate 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful negative scope ('does not start analysis'), but says nothing about freshness, caching, or whether results reflect the current workspace state. With an output schema present, the return shape is handled elsewhere.

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

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

Two short sentences, zero waste, with the positive scope front-loaded and the exclusion immediately after. Nothing extraneous.

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 no-parameter, read-only tool with full annotations and an output schema, the description covers what it reads and what it does not trigger. A bit more on what 'readiness' entails would close the remaining 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. There is nothing for the description to disambiguate, and it correctly avoids inventing arguments.

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: reads workspace readiness and setup links. This is clearly distinguishable from refix_investigate, which it explicitly rules out. However, 'setup links' is not elaborated enough to make the return content fully concrete.

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 sentence 'Does not start analysis' implies the boundary versus refix_investigate, but no sibling tool is named and no explicit when-to-use or prerequisites are given. The agent must infer that this is the pre-flight check before calling investigate.

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 readOnly/idempotent annotations, the description discloses the blocking wait behavior, the polling loop, that it never starts or reruns analysis, and the human-in-the-loop needs_input workflow. These are important operational traits an agent could not infer from the annotations alone.

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

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

The description is four tightly written sentences, front-loaded with the core purpose and immediately followed by the polling and needs_input behaviors. Every sentence carries useful operational 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?

The output schema already describes return values, and the annotations cover safety. The description adds the missing async polling and needs_input workflow context, making the definition complete 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?

The schema has 0% description coverage and the single parameter, investigation_id, is not explicitly defined in the description. The phrase 'investigation started with refix_investigate' implies where the ID comes from, but the description does not directly state that investigation_id is the ID returned by refix_investigate or give format details.

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 gives a specific verb and resource: reading the state of an investigation started with refix_investigate. It also explicitly distinguishes this from the sibling start/rerun tool by saying it never starts or reruns analysis.

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 exactly when to call repeatedly: while queued or running, the call waits up to 25 seconds for a state change, so call it again until it finishes. It also gives explicit handling for the needs_input state, including asking the user and submitting the answer through refix_investigate.

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 and non-destructive, so the safety profile is covered. The description still adds genuine context beyond them: the opaque id is stable across token refresh and reconnects, and no analysis is triggered as a side effect.

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

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

Three short sentences, front-loaded with what is returned and followed by the one non-obvious trait (id stability) and the scope boundary. 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 no-argument read whose output schema carries the return shape, the description supplies enough: identity scope, id stability and the no-analysis guarantee. Slightly incomplete only in that it does not point at refix_get_context as the alternative for context lookups.

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. There is nothing for the description to disambiguate and it correctly avoids inventing input details.

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 ('Return the Refix profile behind this connection') and names the returned entities (signed-in user, workspace). It distinguishes itself from the investigation/watcher siblings by noting it is connection-level identity, though it never names a sibling directly.

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 closing 'Does not start analysis' implies a contrast with refix_investigate, which is a useful exclusion, but there is no positive guidance on when to prefer this over refix_get_context or refix_get_investigation. Usage is inferable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the scope of returned data (status, destination, recent checks), but nothing about how many checks constitute "most recent" or auth requirements — modest added value over 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?

A single tight sentence that front-loads the verb, cardinality, and returned fields. Nothing is wasted.

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 needn't be spelled out, and annotations cover the safety semantics. The only real gap is guidance on sourcing or formatting watcher_id, which the description leaves entirely to the schema.

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?

There is one required parameter, watcher_id, with 0% schema description coverage and no compensation in the description: it doesn't state the ID format or where to obtain it (e.g., from refix_list_watchers). An agent must guess.

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

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

States a specific verb (read) and resource (one watcher) plus the fields returned: status, alert destination, and recent checks. "One watcher" implicitly contrasts with the sibling refix_list_watchers, so an agent can tell them apart.

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 for fetching details of a single known watcher, complementing refix_list_watchers. There is no explicit when-to-use/when-not guidance or mention of alternatives such as refix_get_investigation or refix_get_context.

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

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

The annotations already declare non-read-only, open-world, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new context: 'Counts toward the workspace's Refix usage' discloses a quota cost, and it warns against starting a duplicate investigation to poll progress. It stops short of describing latency or what happens to an existing session when reused, keeping it below a 5.

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

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

Front-loaded with the three modes and the exclusivity rule before the workflow caveats; every clause carries operational content. It is dense and reads as a runbook rather than a crisp definition, which keeps it out of the top band.

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?

Five parameters, all documented, an output schema exists so return values need no explanation, and the description still covers the two things an agent would plausibly get wrong: passing multiple selectors at once and re-investigating to poll for results. Nothing needed 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 each parameter has a description, so the baseline is 3. The description adds a constraint the schema does not encode – the mutual exclusivity of session_id, response_to_input_id and finding_id – plus the guidance that session_id preserves context for follow-ups, which is real value beyond 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 names the specific verb and resource ('Start a new Refix investigation') and enumerates the three call modes: new question, clarification answer via response_to_input_id, and finding drill-down via finding_id. It explicitly names the sibling tools it depends on (refix_list_findings, refix_get_investigation, refix_get_context), so an agent can place it in the workflow 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?

Gives explicit routing rules: 'Send at most one of session_id, response_to_input_id or finding_id', use session_id for follow-ups in the same chat, and 'call refix_get_investigation for the result; do not start another investigation to check progress'. It also prescribes the fallback path when a named tool is not in usable_sources – tell the user it is not connected and ask before starting.

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/destructive=false, and the description adds genuinely new context: default 7-day window, newest-first ordering, and the reassurance that reads create no read receipts or resolutions. It also guards against a common agent error by defining exactly when 'nothing new' is valid. Only the pagination/limit behavior is left implicit.

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

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

Three tight sentences, front-loaded with what the tool returns, then filtering guidance, then the empty-result rule. No filler and every clause carries 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?

An output schema exists, so return values need not be described, and the description covers ordering, default window, incremental reads, and the empty-result caveat. Only the semantics of `limit` (max 50) and `watcher_id` scoping are 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 only 33% (only `since` is documented in the schema), and the description compensates well for `since` by explaining its meaning and default. However, `limit` and `watcher_id` are explained in neither the schema nor the description, leaving two parameters opaque.

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 concrete verb and resource ('Read the proactive updates Refix sent this user'), enumerates what counts as an update (watcher alerts, self-initiated updates, reminders), and specifies ordering and default window. This clearly separates it from siblings like refix_list_watchers or refix_get_context.

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 actionable when-to-do-what: pass `since` (e.g. time of last check) to fetch only newer items, and reserve 'nothing new' for a successful empty response. It lacks explicit pointer to the alternative tool (e.g. refix_get_context) for wider context, so not a full 5.

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, so safety is covered. The description adds genuine value with the permission model ("every workspace member sees every watcher"), but says nothing about pagination behavior or the volume of results returned, which matters for a listing endpoint.

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

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

Two short sentences, front-loaded with the action and scope. No filler, though the second sentence spends its space on visibility rather than the parameters an agent needs.

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, and the read-only profile is annotated. However, for a paginated, filterable listing tool the description leaves all three parameters unexplained, leaving the agent to infer cursor usage from the schema alone.

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% for three parameters, including a pagination pair (limit up to 50, cursor) and a status enum. The description names none of them and gives no hint about paging or filtering semantics, so it does not compensate for the schema 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+resource ("List ... watchers") scoped to the workspace, which cleanly separates it from the singular refix_get_watcher sibling. The phrase "as the dashboard does" is a soft hint rather than a precise specification, but the core operation 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?

No guidance on when to use this versus refix_get_watcher, or how to narrow the listing via the status filter. The visibility note implies the tool is for broad enumeration, but no explicit when/when-not conditions or alternatives are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds genuinely new context about the authorization model ('any workspace member can change any watcher, matching the dashboard') and the immutability of the objective. It stops short of saying whether 'stop' permanently deletes or merely halts the watcher, which matters given destructiveHint=true.

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

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

Three short sentences, front-loaded with the action set and immediately followed by the key constraint and the permission model. 'Matching the dashboard' is mildly decorative but does convey the authorization precedent, so little is wasted.

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

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

An output schema exists so return values need no explanation, and the description covers the mutation scope, the immutable field, and permissions. What remains unsaid is the reversibility of 'stop' and any conditional requirement linking alerts to amend.

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 only 25% (just idempotency_key), so the description has to carry weight: it enumerates all four action values and ties 'alerts' to the amend action ('amend where its alerts go'). It does not state whether alerts is required for amend or ignored for other actions, and watcher_id gets no explanation, keeping it from a 5.

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 concrete verbs (pause, resume, stop, amend) against a concrete resource (a watcher) and scopes the mutable surface to alerts only. It also distinguishes itself from refix_create_watcher by stating the objective cannot change.

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

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

It gives an explicit when-not rule ('The objective cannot change; create a new watcher instead') that routes the agent to the correct sibling, plus the conditions under which each action applies. No inference required.

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