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 for an 11-parameter tool. It discloses one useful trait — fallback to 'containing every word when ranking is unavailable' — but says nothing about pagination (limit/cursor), byte capping (max_bytes), depth of returned data, or whether the operation is read-only.

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?

It is a single compact sentence with no filler, which is efficient, but the telegraphic semicolon-clause style is dense and hard to parse on first read, and the mode-to-parameter mapping is left implicit.

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, eleven-parameter multi-mode query tool with no annotations and no output schema, the description is too thin. Key behaviors — paging, result shaping via depth/format, and the meaning of workspace_id — are entirely undocumented.

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

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

Schema description coverage is only 36%, and the description compensates for just three of the eleven parameters (fetch, about, receipt) — all of which the schema already documents. Sort, depth, limit, cursor, format, max_bytes, and workspace_id remain unexplained anywhere.

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 concrete capabilities — fetch by ref (ID/short ID/exact title), list with fields, semantic search over 'about' words, and receipt lookup — so the agent knows exactly what the tool can do. It never names or differentiates itself from siblings like wirk_show or wirk_status, which likely overlap on the fetch behavior.

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 through the mapping of verbs to parameters (fetch → 'fetch', list → 'fields', search → 'about', lookup → 'receipt'). There is no explicit when-to-use, when-not-to-use, or routing away from wirk_show/wirk_status despite apparent overlap.

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 and does most of it: it discloses that the call is refused, names the two distinct error codes and which case triggers each, and notes the proposal 'waits' (i.e., no side effect occurs). It doesn't describe the successful path in detail, but since the caller can never reach it that omission is minor.

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?

Compact and front-loaded: the decisive constraint ('as an agent this is refused') appears in the first clause. Every element — error codes, wait behavior, the terminal command — adds information. The CLI fragment is slightly cryptic but earns its place by showing the expected decision shape.

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

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

Given no annotations, no output schema, and a tool the agent cannot successfully call, the description supplies what the agent actually needs: that it will fail, why, and who should do it instead. The remaining gap is the decisions payload format for a human-driven call, which the CLI example only partly conveys.

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 25%, and the nested decisions objects (id, revision, action, reason) are undocumented in the schema. The description partially compensates by mapping the CLI 'ID@N' to id+revision and '--reason WHY' to reason, and by exemplifying the 'accept' action. It never explains the decisions array, the accept/reject/defer enum, or the request_id/workspace_id params, so the compensation is only partial.

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 implies the tool submits decisions on proposals ('Only people decide proposals', the CLI form 'wirk review ID@N accept'), but never directly states the verb+resource the agent would be invoking. Instead it foregrounds the refusal, so an agent gets behavior more clearly than the core action. It does loosely separate itself from siblings like wirk_write and wirk_query, but not 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?

It gives strong when-not guidance: as an agent this call is refused, both for your own proposal (not_authorized) and any other (person_required). It then routes to the right alternative — 'Your person decides at their terminal' — making the handoff unambiguous. It stops short of stating any condition under which the agent should call it, which is consistent but keeps it from a 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?

With no annotations, the description carries the full behavioral burden. It does disclose meaningful traits beyond the schema: read-only, link-based access for anyone, and expiry. However, it omits auth/permission requirements, revocation behavior, and any rate/visibility caveats. The ambiguous 'Not live yet' clause further weakens confidence.

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 definition is short and the actionable sentence comes second. The opening 'Not live yet on api.wirk.life: answers views_unavailable' is cryptic and consumes the front-loaded position without conveying a clear condition. Otherwise reasonably efficient.

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

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

For a 6-parameter tool with no annotations, no output schema, and 17% schema coverage, the description does not do enough. It leaves revoke, format, title, and workspace_id unexplained and gives no return-value detail beyond 'its link', while the 'not live' statement leaves the agent unsure whether the tool functions at all.

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 gestures at 'preset status' and 'a view config' (roughly preset/blocks) but gives no meaning for title, format, revoke, or workspace_id. A low-coverage schema is left under-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 core sentence gives a specific verb and resource: 'Make a live, read-only page a person can open... returns its link.' That is clear enough to distinguish from sibling read/write tools. The leading clause 'Not live yet on api.wirk.life: answers views_unavailable' muddies the message and makes the tool's availability ambiguous rather than clarifying its purpose.

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 when-to-use guidance and no comparison against siblings (wirk_status, wirk_query, wirk_write, wirk_review). The mention of 'the preset status or a view config' is parameter-level input detail, not usage guidance. The agent gets no signal about when to pick this over an alternative.

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?

Without annotations, the description carries the full behavioral burden. It discloses 'Writes nothing' which is a key read-only trait, but it omits other relevant behaviors such as permission requirements, response size limits (implied by max_bytes), or rate limits. A score of 3 reflects some useful disclosure but incomplete transparency.

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 short, front-loaded fragment list beginning with 'Start here.' It is concise and avoids waste, though the single run-on sentence could be better structured for scannability. Every phrase earns its place by conveying purpose and 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?

Given no output schema and no annotations, the description covers purpose and read-only behavior reasonably well, but it does not explain the response format, the effect of max_bytes, or how workspace_id and format interact. The 75% schema coverage fills some gaps, but the description leaves a quarter of the parameter surface undocumented.

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

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

Schema description coverage is 75%, so most parameters are documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, and the one undocumented parameter (max_bytes) is not compensated for. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states the tool provides a status overview: who you work for, your work, what's in progress, what needs review, and recent changes. It is specific enough to identify the resource, and 'Writes nothing' hints at read-only. However, it does not name or contrast with sibling tools like wirk_query or wirk_show, leaving differentiation to inference.

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 opening 'Start here' gives clear contextual guidance for when to use this tool as the entry point. It does not explicitly name alternatives or state exclusions, but the implied first-step role is strong. No explicit when-not guidance is present.

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 does well: it discloses atomicity, optimistic concurrency via revisions (basis_changed refusal), a requires_review refusal path, and idempotent retry via request_id after an uncertain result. It omits what the operation returns and any permission/rate-limit context, but the failure-mode disclosure is rich.

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 dense sentences, front-loaded with the core action, but the phrasing is cryptic ('Context changes apply when you may make them') and jams multiple error codes, modes, and retry instructions into a single line. Efficient in size, weak in readability.

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 7-parameter tool with nested objects and no output schema, the description covers behavior well but leaves real gaps: workspace_id and format are unexplained, and with no output schema the 'receipt' the description references is never described. Adequate but not complete.

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

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

Schema coverage is 57%, and much of the description's parameter text (expect format, reason, request_id) restates the schema's own descriptions rather than extending them. It does reinforce the expect-as-basis semantic and the request_id retry contract, but adds little syntax or meaning 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?

States a specific verb and resource: 'Change items and links in one atomic batch.' The atomic-batch qualifier is meaningful and tells the agent this is a multi-operation write. It does not distinguish itself from the read-oriented siblings (wirk_query, wirk_show, wirk_status), but the write/read split is inferable.

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 conditional guidance for mode propose ('Context changes apply when you may make them; otherwise they are refused with requires_review: propose them') and for retries, which is genuinely useful routing. However it never compares against sibling tools or states when NOT to use this tool, so usage is implied rather than explicit.

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