Tirith

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

Despite the annotation being limited to destructiveHint=false, the description discloses rich behavioral details: atomic all-or-nothing acquisition, directory recursion, renewal on re-claim, the brief's side effect of marking notices as seen, and conflict semantics. This goes far beyond annotation coverage and gives the agent a realistic model of the tool's effects.

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 dense but every sentence contributes: atomic semantics, directory behavior, renewal, brief contents and side effects, conflict handling, and explicit alternatives. It is front-loaded with the core action and avoids redundancy with the schema.

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 six parameters and non-trivial concurrency semantics, the description covers the essential behavioral context: atomicity, conflicts, waiting, brief behavior, and alternative tools. The presence of an output schema means return values need not be spelled out, and nothing critical is missing for an agent to invoke this tool 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 the baseline is 3. The description adds meaning beyond the schema by explaining why wait_secs is used (daemon waits for paths instead of retrying), how paths behave with directories, and that re-claiming renews a lease, which enriches the ttl_secs and paths parameters. It does not cover every parameter, but it supplements the schema well.

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 opens with a specific verb and resource ('Lease repo paths to yourself before editing them') and immediately clarifies the atomic scope. It distinguishes itself from siblings by naming claims_list and renew as alternatives, and the lease terminology is unique among the sibling tools.

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 states when to use this tool ('before editing them'), when not to edit on conflict, and when to use wait_secs. It names the alternative tools for non-taking inspection (claims_list) and extension (renew), giving an agent clear routing guidance.

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 readOnlyHint annotation, the description discloses important behavior: expired leases are never listed, newer leases come first, pagination defaults to 20 rows, and next_before drives older-result pagination. This gives the agent a clear model of what the call returns and its 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?

Four dense sentences carry purpose, scope, usage guidance, exclusions, ordering, and pagination with zero filler. The most important scoping information is front-loaded.

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 read-only listing tool with full schema coverage and an output schema, this description covers selection criteria, sibling routing, exclusions, ordering, and pagination. Nothing essential for correct invocation 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%, but the description adds real semantic value by explaining the default behavior of path and all, the meaning of all=true, and how before consumes next_before for pagination. It connects parameters to behavior rather than repeating schema names.

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 live leases' with precise default scope ('yours plus any lease overlapping path') and the conflict-check purpose. It distinguishes itself from siblings like claim and status, so an agent can tell it apart 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?

Explicitly routes usage: 'Use before claim to see who holds a path and until when; for counts and daemon health use status.' This gives both when-to-use and an alternative, leaving nothing 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=true, and the description consistently describes a read operation, so there is no contradiction. It adds useful behavioral context: not_found when no contract exists and invalid when the prefix is ambiguous, plus the fact that all earlier versions are returned.

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 with no wasted words. The core action and scope are front-loaded, followed by usage guidance and error semantics. Highly 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?

The description covers when to use, how to look up, what is returned, and key error conditions. With an output schema present and readOnlyHint annotation, an agent has everything needed to invoke this tool 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 description coverage is 100%, so the schema already documents both parameters. The description adds context about unique prefix validity and lookup semantics, but the parameter meanings are already well covered by the input 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: 'Fetch one contract in full' by name, id, or unique prefix. It explicitly differentiates itself from contract_list, which finds contracts by path or kind, so an agent can immediately tell when this tool applies.

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 when to use: 'when a brief or contract_list names a contract you consume.' It also names the alternative for different lookup needs and documents the failure mode for ambiguous prefixes, leaving little 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=true, and the description adds useful behavioral details: pagination (20 rows per page, pass next_before as before for older rows) and ordering. No contradiction with the read-only hint.

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-load the core action and filters, then add usage context and pagination. 'Rows are compact' is slightly vague, but overall every sentence contributes and there is no fluff.

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 description covers filtering, ordering, pagination, and sibling alternatives. With an output schema present and read-only annotations, an agent has enough to select and call this tool 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 description coverage is 100%, so the baseline is 3. The description reinforces path/kind filtering and cursor usage, but it does not add much semantic meaning beyond what the schema already documents for each 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 uses a specific verb and resource ('List contracts') and names the two filter dimensions ('consumer path or by kind') plus the sort order. It also distinguishes itself from contract_get by explicitly assigning shape retrieval to that sibling.

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 says when to use the tool ('when you are not claiming it') and gives the relevant alternative: a claim's brief already lists dependencies, and shapes come from contract_get. This is clear routing to alternatives without relying on 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 only provide destructiveHint=false, so the description carries the burden and does well: it discloses that republishing an existing name creates a new version, automatically sends change notices to consumers, preserves the consumer list when omitted, and refuses writes via expected_version on concurrent publication.

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 with no filler. The primary action is front-loaded, and each clause adds a distinct behavioral or usage fact: side effects, caller exclusions, preservation semantics, concurrency guard, and read alternatives.

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 publish tool with an output schema, the description covers the key agent-facing concerns: side effects, duplicate-notice prevention, concurrency conflict, optional consumer behavior, and where to read contracts. Nothing essential for correct invocation 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%, so the baseline is 3. The description adds real value beyond the schema by explaining the semantics of consumers ('omitting keeps the list') and expected_version ('refuses the write with conflict if another agent published first'), elevating it above a mere schema restatement.

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: publish the shape of an interface (endpoint, function, type, event, CLI) before implementation, with consumer paths. It clearly differentiates from siblings by naming contract_get, contract_list, and notice_publish as distinct tools.

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 explicit when-to-use context ('before either side implements it'), explicitly warns not to also call notice_publish, and directs read operations to contract_get or contract_list. It also explains republish and conflict semantics, so an agent knows exactly when to use this tool and when not to.

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 readOnlyHint annotation already marks it as safe/read-only, and the description adds meaningful behavioral detail beyond that: case-insensitive search scope, newest-first ordering, 20-row default page size, and how to retrieve older rows using next_before. This gives the agent a solid model of the tool's runtime behavior without contradicting the annotation.

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 sentences deliver the core capability, the primary use case and alternative, and pagination behavior with no filler. Key information is front-loaded, and every sentence earns its place.

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 filtered, read-only list tool, nothing essential is missing: it explains what is listed, how to filter, how results are ordered, how pagination works, and when to prefer it over decision_record. The output schema covers return values, and the annotations cover the read-only safety profile.

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 adds value by clarifying that query searches title, decision, and rationale, and by explaining that next_before from a prior response should be passed as before for older pages. This goes beyond the schema's terse descriptions and helps the agent use the parameters correctly.

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 opens with a specific verb and resource: 'List recorded decisions', then states the filtering modes (affected path or case-insensitive query over title, decision, rationale) and ordering (newest first). It also distinguishes itself from the sibling decision_record, so an agent can tell them apart immediately.

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 explicit usage direction: 'Use before decision_record so nothing is decided twice', which names the alternative and the condition for using this tool. It also notes that a claim's brief already carries decisions for claimed paths, providing a clear when-not-to-use signal, while pagination instructions further clarify how to invoke it.

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 sparse destructiveHint=false annotation, the description discloses important behavior: it writes 'one committed Markdown file under .tirith/decisions/', makes the record appear 'in the brief of later claims on those paths', and returns 'the decision with its permalink.' This gives the agent a clear model of persistence and side effects.

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 sentences cover purpose, storage, side effects, usage timing, alternatives, and return value without redundancy. The core action is front-loaded and every clause earns its place.

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 description is complete for an agent to decide when and how to use the tool: it explains the record's format and location, its effect on future claim briefs, the finality requirement, alternatives, and the return value. Given the rich schema and output schema, nothing essential 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 description coverage is 100%, and each parameter already has a meaningful description, so the baseline is 3. The tool description reinforces the meaning of 'alternatives' and 'affects_paths' but does not add substantive parameter-level semantics beyond what the schema already provides.

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 opens with a specific verb and resource: 'Record a settled project choice with its rationale, the alternatives considered and the paths it constrains.' It clearly states what is recorded and why, and distinguishes itself from siblings by naming message_send and memory_write as alternatives for different situations.

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 condition: 'Use only once the choice is final.' It also names concrete alternatives and their use cases: 'for discussion use message_send, and for lessons about code use memory_write.' This leaves no ambiguity about when to invoke this tool instead of a sibling.

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 declare readOnlyHint=true, and the description reinforces this by stating 'Returns static guidance only', which is valuable behavioral context beyond the annotation. It also clarifies that it does not reflect the daemon's live state, preventing a likely misconception. No contradiction with 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?

Three sentences carry the full purpose, usage guidance, and limitation without redundancy. Key information is front-loaded: what the tool does, when to call it, and what it does not provide. Every sentence earns its place.

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 the simple two-parameter schema with an enum, full schema coverage, an output schema, and readOnlyHint annotation, the description is complete. It covers what the tool explains, when to call it, how to narrow the topic, and how it differs from status, so an agent has everything needed to select and invoke it 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 the schema already documents both parameters. The description adds meaning by explaining that topic 'narrows it to one primitive with when to use each of its tools', which clarifies the purpose of the enum beyond its literal value list. The agent parameter is also given contextual significance in the schema description.

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 ('Explain') and resource ('what Tirith is for and how to work with it'), covering the working loop, reply rules, and tool selection. It clearly differentiates itself from status by noting it returns static guidance only, and from the broader sibling tools by positioning itself as the meta-orientation tool.

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?

Explicit usage guidance is given: 'Call it first in a session, or when unsure which tool fits'. It also explains how to narrow via topic and gives an explicit exclusion: for live daemon state, use status. This leaves little ambiguity about when to invoke this tool versus alternatives.

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 and idempotentHint, but the description adds specific context: 'its file is removed and does not return on restart' and 'Returns a digest of what was removed; not_found if there is none'. This goes beyond the annotations by detailing the permanence and the failure mode, which is valuable for an agent.

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, zero fluff. The core purpose is front-loaded ('Delete one memory note...'), followed by usage guidance and return behavior. Every word earns its place.

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 description covers the tool's purpose, usage vs. alternatives, behavior, and return value. It mentions the output (digest and not_found) which aligns with having an output schema. For a simple delete operation, nothing critical 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?

The schema description for 'name' is 'A permalink, an id, or an exact title' and for 'agent' is 'Your stable agent name'. The description does not add extra meaning beyond the schema – it repeats the same identification options. Since schema coverage is 100%, the baseline is 3, and the description provides no additional parameter context.

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 ('Delete'), resource ('memory note'), and identification method ('by permalink, id or exact title'). It distinguishes itself from memory_write by clarifying that this is for permanent removal, not correction. This clearly separates it from siblings like memory_write and memory_read.

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 states when to use this tool: 'to retract a note that holds a secret or a wrong fact'. It also names the alternative for correcting: 'to correct a note use memory_write, which updates in place'. This is clear, actionable guidance on tool selection.

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, so the safety profile is covered. The description adds value beyond that by disclosing the depth behavior ('depth 1 to 3 adds the notes linked to it, as digests') and the error case ('not_found if there is none'), which are genuine behavioral traits not derivable from the annotations or schema 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?

Four sentences with the core action front-loaded in sentence one, followed by scoping, usage routing, and error behavior. Each sentence earns its place; slightly denser than strictly necessary but no wasted words.

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?

Complete for a read tool: output schema covers return values, annotations cover safety, all parameters are documented, the usage sequence is specified, the depth semantics are clarified, and the not_found failure mode is disclosed. Nothing an agent needs to call 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%, so the baseline of 3 applies — the schema already documents name, agent, and depth. The description adds a small increment by clarifying that depth returns linked notes 'as digests,' but it largely restates the name parameter's meaning in the first sentence.

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 ('Read one memory note in full') plus the identification methods (permalink, id, or exact title). It also differentiates from siblings by asserting 'It is the only tool that returns a note's body,' which cleanly separates it from memory_search.

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 names the sequence and the alternative: 'Use after memory_search or a claim's brief names the note; to find notes use memory_search.' This tells the agent exactly when this tool is appropriate versus its sibling, leaving nothing 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?

Even with readOnlyHint=true, the description adds substantial behavioral detail: rows are digests with a 160-character excerpt and a score, terms match as substrings with no embeddings, and truncated=true signals hidden matches. This tells the agent what to expect without relying on structured fields 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 three sentences and every sentence earns its place: purpose, usage trigger and body-read alternative, then matching and truncation behavior. No filler or redundancy.

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 read-only search tool with full parameter documentation and an output schema, the description is complete. It covers result format, sorting, matching behavior, truncation, and the session-start use 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 coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema by explaining that an omitted query means recent activity and that terms match as substrings. It also defines the truncated flag's meaning in relation to limit.

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 opens with a specific verb and resource ('Find memory notes') and enumerates the search dimensions: free text, path, kind, tag, and time. It distinguishes itself from memory_read by clarifying that search returns digests, not bodies.

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 trigger: with no query, list recent notes, which is 'the call to make when a session starts.' It also names the alternative memory_read for retrieving full bodies, giving the agent clear routing guidance.

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 idempotentHint and destructiveHint annotations, the description discloses substantive behavior: notes are committed Markdown, the next agent claiming the associated paths receives the excerpt, matching titles update in place, permalink allows explicit targeting, and if_updated_at prevents overwriting concurrent edits. This is rich, high-value behavioral context that annotations alone do not provide.

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 three dense sentences with no filler. The first sentence front-loads the core purpose and scope, the second explains update and concurrency behavior, and the third gives exclusions. Every sentence earns its place, making the description easy to parse quickly.

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 8 parameters, the description covers the essential context: what kind of content to store, how it is persisted, how future agents consume it, how to update versus target, how to handle concurrency, and which sibling tools are not appropriate. The output schema covers return values, so the description does not need to repeat them. Nothing critical is missing for an agent to call this tool 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 the baseline is 3, but the description adds real semantic value beyond the schema: it explains that an existing title updates the note in place, that permalink targets a specific note, and that if_updated_at should carry the read value to get conflict detection instead of silent overwrites. This enhances the agent's understanding of title, permalink, and if_updated_at beyond their schema descriptions.

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: 'Save a durable note about repository paths ... as committed Markdown.' It clearly differentiates from siblings by explicitly naming decision_record and message_send as not-this-tool. An agent can immediately understand what memory_write accomplishes and how it differs from nearby alternatives.

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 gives explicit when-to-use context ('a lesson, trap, handoff or research') and explicit when-not-to-use alternatives ('Not for settled choices (decision_record) or talk between agents (message_send)'). It also provides operational guidance about updating existing titles and using if_updated_at for concurrency, leaving little 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=true; the description adds meaningful behavior beyond that: newest-first ordering, the inbox-vs-history nuance, the human-queue special case, and 20-row pagination with next_before. It stops short of describing the response shape, but the output schema covers that.

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-load the core behavior and filters, then provide usage guidance and pagination. Every clause earns its place; there is no repetition of the schema or 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 read-only list operation with a rich output schema and 100% parameter coverage, the description is sufficient: it covers filtering, ordering, pagination, the human-queue special case, and the polling caveat. An agent has everything needed to call the tool 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 description coverage is 100%, so the baseline is 3. The description adds valuable extra semantics: with=human maps to the human queue thread, before accepts a previous response's next_before, and the default page size is 20. These details go beyond the schema's field descriptions.

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 opens with a precise verb and resource: 'List your own conversations, sent and received, newest first'. It specifies scope, ordering, and filter dimensions, clearly distinguishing it from siblings like message_send, claims_list, and task_list.

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 explicit usage direction: 'use this for history, not to poll', explaining that new messages already arrive as inbox on every reply. It also documents the special human-queue case ('with=human shows the human queue thread') and the pagination 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?

The description discloses key behavioral traits beyond the annotations: messages are delivered only once, appear as inbox on the recipient's next tool call, support reply_to threading, and are dropped after 24 hours. This goes well beyond the sparse destructiveHint annotation and gives an accurate model of side effects.

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 compact and well-structured: first the core send action and recipient types, then delivery semantics, then explicit usage boundaries, then retention. Every sentence adds necessary information without repetition or 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 tool with 5 parameters and an output schema, the description covers the important behavioral context: who can receive, how delivery works, how replies thread, when to use it, and what it is not for. The remaining parameter details are already fully documented in the schema, so nothing critical 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?

The input schema already covers all parameters with descriptions, so the baseline is 3. The tool description adds extra meaning by explaining the special recipient values ('*', 'human'), the threading behavior of reply_to, and the overall 'short message' intent, which clarifies how parameters should be used.

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 clearly states the tool's function: sending a short message to one agent, all active agents, or the human queue. It differentiates from siblings by explicitly naming alternatives like memory_write, decision_record, and notice_publish, and by describing the delivery mechanism.

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 explicitly says 'Use for coordination talk; not for lasting knowledge (memory_write, decision_record) or for code changes others must react to (notice_publish).' This gives an agent clear when-to-use and when-not-to-use guidance, naming the exact sibling tools to use instead.

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 discloses a critical side effect beyond the annotations: 'Listing unread notices marks them seen by you, durably, so they do not come back.' It also reveals pagination behavior with 20-row pages and the next_before cursor semantics, which annotations do not cover. No contradiction with destructiveHint=false exists since marking-as-read is not destructive.

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 tight, front-loaded with purpose, then scope, side effect, alternative routing, and pagination. Every sentence adds distinct value with no filler or redundancy. It is dense but immediately scannable.

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 7 parameters and no output schema details in the description, this is complete: it covers what the tool does, how unread scoping works, the side effect of reading, when to use an alternative, and pagination mechanics. The existing output schema covers return shape, and the agent parameter is explained in 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning beyond the schema: unread without path is scoped to held paths, all=true expands beyond them, and next_before from a prior response should be passed as before for older pages. This is substantive supplementary semantics beyond the individual parameter descriptions.

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 opens with a specific verb and resource—'List change notices'—and immediately distinguishes filtering dimensions: path, since time, and unread status, with ordering. It also contrasts with the claim brief and notice_publish sibling, so an agent can identify this as the retrieval tool rather than a mutation tool.

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 explicitly tells the agent when NOT to use this tool: 'A claim's brief already delivers the unread notices for the paths it claims; use this for other paths or older pages.' This is clear routing guidance, and the unread/all scoping rules further clarify which invocation is appropriate.

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 only destructiveHint=false in the annotations, the description carries most of the behavioral disclosure burden. It reveals the side effects: 'Every other agent holding an affected path gets it in its inbox at once' and the rest see it in the brief of their next claim. This lets an agent anticipate the reach of publishing a notice.

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 sentences with the purpose first, usage second, and consequence third; no filler or repetition. The longer third sentence earns its place by describing the delivery mechanism.

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 4 required parameters, an output schema exists and every parameter is documented in the schema. The description supplies the remaining usage rule and behavioral consequences, so nothing essential seems 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 100%, so the structured fields already define kind, from/to, and affected_paths. The description only renames these ('with from, to and the affected_paths') and does not add format, edge-case, or constraint details 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 opens with a specific verb and object: 'Announce a change other files must react to' and enumerates concrete change kinds ('rename, signature change, removal, move or behavior change'). It also explicitly distances itself from interface-shape changes, which are 'contract_publish' territory, so it is distinguishable from its sibling tools.

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 use it: 'Use after changing something used outside the paths you claimed.' It also gives a clear exclusion: 'not for interface shapes, which contract_publish versions and announces itself,' pointing to the alternative sibling.

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 idempotentHint=true and destructiveHint=false, and the description does not contradict them. It adds useful behavioral detail beyond annotations: exact path matching, the file#Symbol anchor nuance, and atomic not_found behavior where nothing is released. This is strong supplementary 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 compact at three sentences with no filler, and it front-loads the core purpose. The structure could be slightly smoother, but every sentence contributes necessary information about behavior, usage, or edge cases.

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 only two parameters, a full-coverage schema, and a provided output schema, the description covers purpose, usage, alternatives, exact matching, error behavior, and release-all semantics. Nothing essential appears to be missing for an agent to invoke the tool 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 the baseline is 3. The description adds meaningful semantics beyond the schema: omitting paths releases everything held, path matching is exact, and releasing a file does not release embedded anchors. These details help the agent use the paths parameter correctly.

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 opens with a specific verb and resource: 'Give up leases so other agents can claim the paths', and clarifies the omit-paths release-all behavior. It also distinguishes this tool from siblings like renew and claims_list, so an agent can tell it apart without inspecting 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?

It explicitly states when to use the tool ('Use when you finish editing') and what not to use it for ('not to extend time (renew) or to inspect (claims_list)'). This gives clear, actionable routing guidance with named alternatives.

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 idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: the TTL extension mechanism, the four-TTL age-limit restart, the 'not_found' outcome, and the fact that any tool call renews. No contradiction with 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?

Three tight sentences each earn their place: first states the core behavior, second gives usage guidance, third covers return values. No fluff, and the most important information is front-loaded.

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 one-parameter tool with an output schema and safety annotations, the description fully covers behavior, usage conditions, alternatives, return values, and error cases. 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 agent parameter is fully documented in the schema. The description does not add parameter-level detail, which is acceptable because the schema already carries that burden.

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 action (extend leases by original TTL) and resource (all held leases), and explicitly contrasts with claim for taking new paths. It clearly differentiates renew from its siblings.

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 gives an explicit when-to-use condition ('Needed only during long work with no other call'), explains why (any tool call already renews), and names the alternative for different situations ('to take new paths use claim').

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 carry readOnlyHint=true, and the description reinforces this with 'publishes nothing and takes no lease' – a more specific behavioral disclosure about side effects. It also surfaces the verbose behavior (lists up to 50 active agents) and the report's contents. While it doesn't discuss auth or rate limits, the core side-effect transparency goes beyond the annotation and is meaningful for an agent deciding whether to call this safely.

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 compact and front-loaded with the tool's core purpose, followed by usage guidance and alternatives. Every sentence earns its place: health report contents, verbose behavior, when to use, and explicit exclusions. There is no filler or repetition, making it easy for an agent to scan and act.

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 read-only health check with no required parameters, the description covers all necessary context: what the report contains, how verbose changes output, that it has no side effects, and how to choose alternatives. The presence of an output schema means return-value details need not be in the description. Nothing critical is missing for an agent to call this tool 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 description coverage is 100%, so the baseline is 3. The description does not add new meaning to the 'agent' parameter beyond the schema, and for 'verbose' it essentially restates the schema description ('verbose=true adds up to 50 active agents with what they hold'). It adds no format, default, or interaction detail not already present in the structured field descriptions, so no bonus is warranted.

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 opens with a specific verb and resource: 'Report the daemon's health', then enumerates the exact content of the report (counts, swarm lead, persistence failure, skipped files). It also distinguishes itself from siblings by explicitly stating it 'publishes nothing and takes no lease', which sets it apart from tools like claims_list or notice_publish. An agent can immediately know what this tool is for and what it is not.

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 gives explicit usage direction: 'Use for a health check or to find the lead'. It also provides clear exclusions and alternatives: 'it publishes nothing and takes no lease. For your own leases use claims_list, and for how to work with Tirith use guide.' This is exactly the kind of when-to-use/when-not-to-use guidance that lets an agent route correctly without opening sibling schemas.

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?

Goes well beyond the sparse annotation (destructiveHint=false) by disclosing key behaviors: depends_on blocks until dependencies complete, higher priority is pulled first, paths help task_pull avoid file collisions, and the tool returns the created task with its id. It also clarifies the tool only queues work and does not start it.

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 purpose, then key behavior, then routing guidance. Every sentence earns its place with no redundancy.

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 an output schema present and full parameter descriptions in the schema, the description is complete for an agent deciding whether and how to call it. It covers purpose, workflow semantics, alternative tools, and return value.

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 already 100%, so the baseline is 3. The description adds meaning on top by explaining the workflow effect of depends_on, priority, and paths in relation to task_pull, which the schema descriptions only partially 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?

Description opens with a specific verb and resource: 'Add a todo task to the shared board for any agent to pull.' It clearly differentiates from siblings by explicitly naming task_pull and task_update and stating what each sibling does.

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 states when to use this tool vs alternatives: 'Use to queue work, not to start it: task_pull assigns work and task_update changes a task.' This gives an agent direct routing guidance between sibling tools.

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, so the safety profile is covered. The description adds useful behavioral context beyond that: it is non-destructive ('without taking anything'), it returns compact rows, it paginates at 20 rows per page, and it orders by most recently updated. It also explains the cursor semantics ('pass next_before as before'). This adds meaningful behavioral detail without contradicting the annotation.

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 sentences, no filler. The core purpose and ordering are front-loaded, the usage distinction comes second, and the pagination detail is last. Every sentence earns its place and the whole description is compact.

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 read-only list tool with a 100%-covered schema and an output schema present, the description covers the essential behavioral aspects: what it lists, how it filters, how it orders, how pagination works, and when to use the sibling instead. Nothing an agent needs to call 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 description coverage is 100%, so the schema already documents all five parameters. The description adds a little extra meaning by explaining the pagination cursor relationship ('pass next_before as before') and the default/max row counts, but it doesn't need to compensate for any schema gaps. 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 a specific verb ('List'), a resource ('tasks on the board'), and two filtering dimensions (status or owner), plus an ordering rule (most recently updated first). It also distinguishes itself from the sibling task_pull by explicitly saying it is for inspection, not taking work. This is a clear, specific purpose that an agent can act on without opening the schema.

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 explicitly says when to use this tool ('inspect the board without taking anything') and names the alternative for taking work ('to take work use task_pull'). It also gives pagination guidance ('pass next_before as before for older rows'). This is explicit when/when-not guidance with a named alternative, which is exactly what the dimension asks for.

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 sparse annotation (destructiveHint=false), the description discloses that the selected task 'becomes in_progress and yours', describes the path-preference selection strategy, clarifies that wait_secs 'waits server-side for work instead of you polling,' and explains the meaning of 'none' and 'waiting_on' for coordination. There is no contradiction with 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?

Every sentence earns its place: the first delivers the core action and selection rule, the second routes to alternatives, and the third clarifies return semantics and the wait parameter. The most important information is front-loaded, and there is no filler or repetition of schema content.

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 the tool's moderate complexity, an output schema exists, and the annotation is minimal, the description covers selection algorithm, side effect (ownership), usage alternatives, and edge-case interpretation ('none' and 'waiting_on'). It provides everything an agent needs to invoke the tool correctly and handle the result, making it complete for its context.

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 100%, so the baseline is 3 with both parameters already documented. The description adds extra behavioral nuance for wait_secs ('waits server-side for work instead of you polling') that is not in the schema, lifting it above baseline. The agent parameter is not further elaborated, but the schema's 'Your stable agent name' is sufficient.

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 opens with 'Take the next task' – a specific verb and resource – then precisely defines the selection criteria (highest-priority todo with dependencies done, becoming in_progress and yours). It also explicitly differentiates from task_list and task_update, so an agent can distinguish the tool from key siblings 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?

The description states exactly when to use this tool ('Use to get work') and when not to, naming alternatives: 'to look without taking use task_list, and to change a named task use task_update.' It also provides post-return guidance about interpreting 'none' and coordinating on 'waiting_on' tasks, covering when-to-use and exclusion criteria explicitly.

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 idempotentHint and destructiveHint annotations, the description discloses conflict behavior when another agent has the task in_progress, the meaning and effect of force, and that the action is recorded in the task's notes. It also states the return value is the full task, adding useful behavioral context not present in 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?

Three dense sentences deliver the essential information in order: status semantics, conflict/force rules, alternative routing, and return value. There is no filler or repetition of schema details.

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 the output schema exists and annotations cover safety, the description sufficiently covers all status transitions, conflict handling, force behavior, note usage, return shape, and the main sibling alternative. Nothing important is missing for an agent to invoke the tool 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 the baseline is 3, but the description adds real semantic value by explaining what each status means in context: done finishes, todo hands back, blocked parks with a note as reason, and in_progress takes by id. It also clarifies the force/note interaction beyond the raw parameter descriptions.

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 opens with a specific verb and resource: 'Change one task's status,' then maps each allowed status to its intended effect. It also distinguishes itself from task_pull by pointing users to that sibling for getting the next task without naming one.

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 clearly states when to use the tool and gives an explicit alternative: 'To get the next task without naming one use task_pull.' It also explains the conflict scenario and force flag. It doesn't enumerate all sibling exclusions like task_create or task_list, but the primary routing guidance is solid.

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