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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description's second sentence adds genuinely non-obvious behavior about how a 'label: query …' result maps bare refs and KEY=VALUE pairs, but it says nothing about pagination (cursor/limit), what depth controls, or response size shaping beyond what the schema 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?

Only two sentences and no filler, with the mode list front-loaded. However the second sentence is a dense run-on about result-label parsing that forces re-reading, and the mode enumeration is packed into a semicolon chain rather than structured.

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 12-parameter, five-mode, nested-object tool with no output schema, the description covers the ref/query grammar but omits paging, depth semantics, format selection, and how the modes interact with limit/cursor. An agent can pick a mode but cannot confidently call it correctly in the list/pagination path.

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 58%, so the schema already documents sort, wait, about, fetch, fields, receipt and max_bytes. The description adds the KEY=VALUE-to-fields mapping rule and the comma-as-list exception for text/linked/folder, which is real added meaning, but it leaves depth, limit, cursor, format and workspace_id entirely unaddressed in both places.

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 enumerates four modes (fetch by ref, list with fields, meaning search via about, receipt lookup), which goes beyond a tautology, but the phrasing is heavily compressed ('find what matters for about') and never names or distinguishes the siblings wirk_show or wirk_review, which plausibly overlap on reading records by ID.

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 conditional offered is '(by meaning on Pro)' for the about mode. There is no statement of when to use this versus wirk_show or wirk_write, no prerequisites, and no exclusions; an agent must infer mode selection entirely from parameter names.

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=false and idempotent=true, so the description is not obligated to restate mutability. It adds genuinely non-schema behavior: the authorization failure mode (not_authorized) and the prohibition on background agents deciding, which an agent could not infer from structured fields. It leaves the stale-revision outcome and the effect of a rejection unspecified.

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

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

Three tight sentences with no filler, and the core action is front-loaded. 'At the revision you read' is compressed to the point of being slightly cryptic, and 'A background agent never decides' reads as a fragment, but 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?

For a mutation tool with no output schema and 0% schema coverage, the description covers the decision-critical pieces: who is permitted, what happens if not, and revision pinning. The remaining gaps (stale-revision conflict behavior, request_id idempotency key semantics) are real but secondary.

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 carry the load, and it only partly does. It gives real semantic content for the decisions array (action verbs map to the enum, 'the revision you read' explains why revision is required and what pinning means), but reason, request_id, workspace_id and format are never mentioned.

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 set of verbs (accept, reject, defer) against a named resource (proposals) with a scoping constraint ('at the revision you read'). An agent knows exactly what operation this performs, though it never names a sibling tool to contrast against wirk_write or wirk_query.

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 defines eligibility ('Anyone whose role may review decides') and two exclusion cases: non-review roles receive not_authorized, and background agents never decide. That is concrete when/when-not guidance, but it stops short of routing the agent to a specific alternative for the excluded cases.

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 genuinely useful behavior beyond annotations: link-based open access, a 24-hour expiry, and that a link is returned. However, it omits that the tool mutates state (annotations correctly say readOnlyHint=false, which the wording 'read-only page' could mislead a reader into overlooking), and it does not explain what revoke does or whether anyone with the link can re-share.

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 with the most decision-relevant facts (link return, expiry) front-loaded and no filler. Slight cost: cramming 'preset status or a view config' into one clause makes the input options harder to parse than a short list would.

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?

No output schema exists, and the description does usefully say a link is returned, so the return side is covered. Against 6 mostly-undocumented parameters and an undocumented revoke path, though, an agent still lacks enough to call this correctly in all but the simplest preset case.

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 17% across 6 parameters, so the description must compensate and largely does not. It hints at 'preset' and 'view config' (blocks) but says nothing about title, format, workspace_id, or the operationally significant revoke string — the one parameter an agent most needs explained.

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 conveys that a live shareable page for a person is produced and its link returned, which is a clear enough resource+outcome. But it never states the action verb (create/share), and the phrase 'live read-only page' describes the artifact rather than the operation, leaving ambiguity about whether this publishes or merely reads. Sibling differentiation is only implicit via 'preset status', which brushes against wirk_status without clarifying the boundary.

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 statement of when to choose this over wirk_status, wirk_query, or wirk_write, nor any prerequisites (workspace scoping, creation vs. revocation). The revoke parameter is never acknowledged, so an agent gets no routing signal for the teardown path.

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

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

'Writes nothing' merely restates the readOnlyHint=true and destructiveHint=false annotations, earning no additional credit. Nothing is said about output size behavior despite a max_bytes parameter, nor about how 'recent changes' are scoped (time window, workspace boundary). With annotations already covering the safety profile, the description adds essentially no new behavioral context.

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 'Start here' so the agent gets the routing cue immediately. 'Writes nothing' is a wasted clause given the annotations already say so, but overall the text is tight.

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

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

For a zero-required-parameter read tool with full annotations and no output schema, the description gives an adequate sketch of the returned sections. It still leaves format vs. default text output, max_bytes truncation behavior, and the meaning of 'recent' unexplained.

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% and the description mentions no parameters at all — task, workspace_id, format and max_bytes are entirely undocumented in prose. The relevance-filtering behavior of 'task' is useful but lives only in the schema, so the description fails to compensate for the uncovered max_bytes and format 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?

The description enumerates what the tool returns — 'who you work for, your wirk, what waits, and recent changes' — which reads as an orientation/dashboard summary rather than a query or write. 'Start here' establishes it as the entry point relative to siblings like wirk_query and wirk_show, though it never names an alternative 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?

'Start here' is real ordering guidance: call this first. But there is no statement of when to prefer wirk_query, wirk_review or wirk_show afterwards, and no exclusions or prerequisites. Usage is implied by sequencing only.

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 (readOnly=false, destructive=false, idempotent=true) the description discloses the atomicity contract, optimistic-concurrency behavior via revisions ('missing revisions get basis_changed'), and the review/propose escalation path. It does not say what the receipt looks like or how partial failures are reported, but the safety profile added here is well above annotation coverage.

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 purpose is front-loaded and there is no filler, but the two follow-on sentences are densely packed clauses that trade readability for brevity. For a tool with eight operation types, the compression pushes detail an agent needs out of reach rather than earning 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?

The heavy per-operation detail correctly lives in the operations schema, so the description need not repeat it, and there is no output schema to explain. What remains missing is the receipt/return shape and the fact that reason is also mandatory for archiving, both of which the schema mentions only in passing.

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 57%, and the description adds real meaning for 'expect' (which IDs and revisions to supply, and the contributes_to parent rule) and for 'reason' tied to proposing. It says nothing about 'mode', 'format', 'workspace_id' or 'request_id', and those gaps are only partially covered by the schema's own descriptions, so a baseline 3 fits.

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 first sentence gives a specific verb and resource set ('Change items and links atomically'), which cleanly separates it from the read-oriented siblings wirk_query, wirk_show and wirk_status. The remaining sentences stay on topic but rely on internal vocabulary (rN, basis_changed, contributes_to) that softens the clarity slightly.

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?

'Context changes apply when you may make them; requires_review means propose with a reason' does hint at the apply-vs-propose decision, but only for the review case. It never names a sibling tool or states when to prefer this batch write over, say, wirk_review, and the conditions are phrased as jargon rather than decision rules.

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