Arroway

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations: the digest is rolling and expandable, open handoffs are kept in a separate block and never displaced, and read_id/receipt act as a cursor over a frozen window during paginated reads. This meaningfully enriches the annotation-only picture.

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 longer than average but every sentence carries distinct operational value: the start-of-session instruction, the digest contents, handoff separation, pagination mechanics, and the sibling distinction. It is front-loaded with the most critical call-time instruction, and no sentence is filler. Slightly dense, which prevents a 5.

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 no output schema, the description covers what an agent needs to invoke it correctly: when to call it, what it returns conceptually, how to continue multi-part digest reads with the cursor, and when to delegate to arroway_read. It also accounts for the session-start workflow and the non-displacement of open handoffs, making it complete in 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 coverage is 100%, and the single optional days parameter is already well documented in the schema with default, bounds, and a usage cue ('Ask for more only when you are picking up work after being away'). The description does not need to repeat parameter details, so the baseline of 3 is appropriate.

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: it opens a rolling, expandable digest of recent activity across every project the person belongs to, plus a roster of projects. It explicitly distinguishes itself from the sibling arroway_read ('this is the where-do-things-stand read; arroway_read is the task-specific one'), so an agent can select it correctly without opening other 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 gives an explicit usage rule: 'Call this ONCE at the START of a session, before there is a task.' It also names the alternative arroway_read for full-body content and contrasts session-level catch-up with task-specific reading, providing both when-to-use and when-not-to-use 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?

Adds substantial behavioral nuance beyond annotations: a claim is a mark, never a lock, stops nobody, overwrites on re-claim, and a stale claim is information. This supplements idempotentHint=true and clarifies non-destructive semantics. The addressing rule also discloses how autonomous vs. human sessions should behave.

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, each carrying distinct information: the action and rationale, the mark-versus-lock semantics, the addressing rule, and the follow-up tool. The main action is front-loaded and every sentence earns its place with no filler.

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

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

The description covers behavior, timing, ownership rules, and follow-up, but leaves the project parameter unexplained and doesn't mention what a successful claim returns. Given no output schema, these are minor omissions; the core behavior is well specified enough 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 coverage is 67%, with project lacking a description. The description adds context for handoff and note (e.g., 'saying whose it was') but does not explain the project parameter at all. It provides some meaning beyond the schema but does not fully compensate for the missing project semantics.

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 states a specific verb and resource: 'Mark that you are taking an open handoff,' and clearly scopes the action with 'BEFORE working on it' and the parallel-session purpose. It also contrasts a claim with a lock and names arroway_close as the follow-up, making the tool's role distinct among 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?

Explicitly says when to use it ('BEFORE working on it') and why (prevent duplicate work). It provides clear when-not guidance via the addressing rule: autonomous sessions must leave handoffs addressed to someone else, while only a human may decide otherwise. It also routes to arroway_close when work lands.

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 establish mutating, idempotent, and non-destructive traits. The description adds contextual behavior: closing without a completion log leaves 'an ending with no story,' and an open handoff whose object is gone 'keeps billing a person for work that no longer exists.' This enriches the safety profile without contradicting 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?

The description is front-loaded with the primary use case, but it is verbose with multiple conditional clauses and rationale. While every sentence adds context, the length is excessive for a tool description. It could be tightened without losing essential guidance, so it earns a middle score.

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 nuanced edge cases (closing others' handoffs, the companion log requirement, and the exclusion of active handoffs), the description covers all relevant scenarios and constraints. No output schema exists, so return values are not required. It gives an agent enough to call 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?

The schema describes handoff and note; project lacks a description but has a pattern. The description gives guidance on the note ('a note naming what emptied it') and implies the required parameters through context. With schema coverage at 67%, the description adds some semantic value but does not fully compensate for the missing project description. Baseline 3 is appropriate.

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: 'Close an open handoff' when the work is done. It clearly distinguishes this tool from siblings like arroway_log (which records residue) and arroway_retire/withdraw (discarding is human-only). The scope and intent are unmistakable.

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 to call it alongside arroway_log, and clarifies when it applies to someone else's handoff ('when your work emptied it'). It also states what is NOT this tool: a handoff still carrying real work must never be closed by a passer-by, and discarding is the human's gesture in the panel. These clear conditions route an agent correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the tool closes the sequence and records receipt of the whole snapshot, and clarifies that delivery is recorded earlier. This goes beyond the structured fields and doesn't contradict them.

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 filler. The main action is front-loaded, and the clarification about preconditions is valuable. 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 simple two-parameter tool with no output schema and annotations covering safety, the description is sufficient. It explains when to call, what it does, and a key non-requirement. No critical information is missing for correct invocation.

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

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

Schema coverage is 100% with both parameters described in the schema. The description mentions 'read_id and receipt' but doesn't add new semantic detail beyond connecting them to the process. Baseline 3 is appropriate given the schema already documents the 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 clearly states the action: acknowledge a multi-part Arroway read with read_id and receipt to close the sequence. It uses a specific verb and resource, and the context of 'final part' distinguishes it from other read-related tools, though it doesn't explicitly name sibling 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 timing guidance ('After the final part... arrives') and an important exclusion ('It is not a precondition for working'), which helps an agent decide when to invoke this tool. It doesn't mention alternatives but the usage context is clear.

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 meaningful behavioral context beyond the annotations: it stores only domain and labels, never visitor addresses or browsing history, and calling it again for the same domain replaces the existing mapping. This complements the idempotentHint annotation and warns about the overwrite behavior, which is important for an operational setting.

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 focused sentences, each earning its place: purpose, usage context and permissions, privacy, and overwrite behavior. It is front-loaded with the core action and avoids redundant restatement of the title or 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 three-parameter configuration tool, the description covers the core purpose, the trigger condition, the required permission level, the stored data scope, and the overwrite behavior. No output schema exists, but the description sufficiently explains the effect of the call for an agent to 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 description coverage is 100%, so the parameters are already well documented in the schema. The description reinforces that source and channel are short labels and clarifies that only domain and labels are stored, but it does not add substantial new parameter-level meaning beyond what the schema 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 uses a specific verb and resource: configuring how a known external referrer is counted in Arroway's acquisition view. It clearly states the mapping from domain to source and channel, making the tool's purpose unmistakable and distinct from all listed siblings, none of which concern referrer configuration.

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 to use it when a product administrator asks to map a domain to a source and channel. It also adds relevant context by noting it is a product-wide operational setting with administrator-only availability, though it does not explicitly mention when not to use it or name alternative 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 and destructiveHint, and the description adds meaningful behavior: each call acknowledges the previous part, returns the next one, and the first part already counts as a delivered read. This goes beyond the structured annotations without contradicting them.

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 compact sentences, front-loaded with purpose, followed by mechanics and usage criteria. Each sentence contributes; the optionality point is slightly repeated in the final warning, but the overall structure is tight and 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 two-parameter continuation tool with annotations and no output schema, the description explains the return behavior, acknowledgement semantics, and the decision context well. It could mention how the end of the read is signaled, but that is not essential 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 coverage is 100%, and both parameters already have descriptive text in the schema. The description reinforces that read_id and receipt must come from the preceding part, but it does not materially add new semantic information beyond that.

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: 'Fetch more of an Arroway read that did not fit in one response.' It clearly distinguishes continuation from the initial read and sibling tools by explaining that each call acknowledges the preceding part and returns the next 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 gives an explicit when-to-call condition: only when something in the first part's list of later contents bears on the task, and it warns not to call as a formality. It does not name alternative sibling tools, but the relevant alternative—not continuing—is directly addressed.

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 substantial behavioral detail beyond the readOnlyHint and idempotentHint annotations: only sanctioned live memories travel, proposals/archived memories/findings are excluded, findings remain in the project and the answer reports their count, and no people-related data is exported. It also explains that the pack name is the trust signal for the recipient.

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 main purpose is front-loaded and the filtering rules are grouped logically. However, the point about people-related data not traveling is stated twice ('Nothing about people travels...' and 'The pack is what the team decided, never who was there'), making the text slightly more redundant than necessary.

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 absence of an output schema, the description still explains what the result is (a portable document), what it contains, what is filtered out, and what the answer reports (how many findings stayed). Together with the fully described input schema, nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's only parameter-specific comment—'Give it a name that says what it is for'—largely duplicates the schema's `name` description, so it adds no significant new semantic value beyond baseline.

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

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

The description opens with a specific verb and resource: 'Export what this project has DECIDED as a portable memory pack.' It clearly distinguishes the tool's scope by defining what counts as a norm (sanctioned, live memories) and what does not, and contrasts with the sibling arroway_import by mentioning import as a downstream use case.

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 clear use context: hand it to another team, keep it as a file, or import it into another project. It does not explicitly name sibling tools as alternatives or state when not to use it, so it falls short of a 5, but the intended scenarios are concrete and recognizable.

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 several behaviors beyond the annotations: everything lands as a proposal, never as an active rule; pinning is deliberately not done because it spends reading budget; malformed documents cause a total refusal with a count of omitted units. This is rich behavioral disclosure that goes far beyond the simple annotations (readOnlyHint false, destructiveHint false). 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?

The description is front-loaded with the main action, then explains the proposal status, pinning, and atomicity. Each sentence adds information, though it is fairly long. It is well-structured, not padded, and every sentence contributes to understanding the tool's behavior.

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 main behavioral aspects, parameter guidance, and edge cases (malformed documents). It does not mention the return value, but no output schema exists, so the description could have addressed that. Overall it is fairly complete for the tool's complexity.

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 already describes both parameters with 100% coverage. The description adds critical context: the pack must be read and passed as an object (not a URL), and the project slug must be verified against the roster. This adds meaning beyond the schema and helps the agent avoid common mistakes.

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: 'Bring a memory pack into a project.' It then clarifies the outcome (everything lands as a proposal, never an active rule) and distinguishes the tool from siblings like arroway_export by stating what it does not do. This is not a tautology and is immediately understandable.

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 clear context for when to use this tool: when you have a memory pack to bring into a project. It sets expectations that the pack is never activated, so it is for importing as proposals. It does not explicitly name alternatives, but the purpose is clear enough for an agent to infer when to choose it. It also hints at verification of the project slug, which is useful 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?

The description goes well beyond the annotations: it discloses that fulfilled memories are retired in the same act, that the retirement is reversible 'from the panel', that entries without an essence are marked as pending a reviewable proposal, and that the call is refused if any fulfills item fails. These are meaningful side-effect behaviors. No contradiction with annotations exists; readOnlyHint=false and destructiveHint=false are consistent with an append-plus-retire operation that is reversible.

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 and long, but almost every sentence adds operational guidance. It is front-loaded with the primary purpose and then layers correctness rules. Some repetition and capitalization make it harder to scan, but the length is largely justified given the tool's complexity and the important side-effect behavior that must not be missed.

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 9-parameter write tool with no output schema and partially informative annotations, the description is thorough. It explains the write obligation, the essence rule, the fulfills/retirement behavior, and the exception for frozen catalogs. The remaining gaps — such as explicit guidance for operational, backfilled, topic, and source — are adequately covered in the input schema's own descriptions, so the description is not incomplete enough to cause misinvocation.

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 substantial guidance beyond the schema. It explains what should go into content ('say what carries, cut what does not'), that essence is mandatory for normal entries, which dated states belong in the log, and what 'fulfills' means in terms of killing conditions. This materially improves an agent's ability to populate the most nuanced fields.

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: 'Append the durable residue of a COMPLETED task to your daily log in Arroway'. It clarifies the tool is for durable, team-visible task residue and explicitly distinguishes it from other log/read tools by emphasizing this is what remains after completion. This is specific enough to differentiate it from sibling tools like arroway_remember or arroway_pass.

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 clear context: use it for completed task residue, not for conversation transcripts or open work. It also says what belongs here ('Dated state', 'the person corrected you...') and what does not, and explains the fulfills mechanism. It does not explicitly name alternative tools or give explicit 'when not to use' exclusions, so it stops short of 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?

Goes beyond annotations by explaining the queuing behavior ('only queues the change for the human's review') and the visibility consequences of a move (team vs personal exposure). Annotations already cover idempotency and non-destructiveness, so the description adds useful context without contradiction.

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 front-load the core purpose, then behavior, then parameter source. Each sentence earns its place; no filler.

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

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

The description covers purpose, usage context, behavioral consequences, and parameter source. It doesn't describe the return value, but there is no output schema, and the human-review outcome is explicitly stated. Some missing details like failure conditions are minor.

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 covers all four parameters at 100% with clear descriptions. The description adds the source for memory ('Use the #handle from the read') but that is already present in the schema. No additional 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 ('PROPOSE'), resource ('a memory belongs in a different project'), and distinguishes itself from actually moving by saying 'you never move it yourself' and 'only queues the change for the human's review.'

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

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

Gives clear context for when to use it (when you believe a memory belongs elsewhere) and instructs to use the #handle from the read. It stops short of naming alternative sibling tools, but 'you never move it yourself' establishes that this is the proposal path, not the execution 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial context: it returns a map of titles/handles rather than content, it does not answer 'how do I do this', it prints a session checkpoint that can be passed back, and the server decides whether to reprint norms. These behavioral details go well beyond the annotations and clarify the tool's side effects and repetition semantics.

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 long but well-structured: it front-loads the primary use, then explains the map, the `since` mechanism, and the distinction from arroway_read. Every sentence serves a purpose, though some could be tightened. It earns a 4 because the length is justified by the tool's complexity and the need to convey nuanced behavior.

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 no output schema, the description must explain return values, which it does thoroughly: standing norms, a map of titles/handles, and a session checkpoint. It also covers the cost implications of passing `since` and the relationship with arroway_read. An agent has all the information needed to call it correctly and interpret results.

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%, yet the description enriches both parameters: it explains `since` as the checkpoint from a previous call and clarifies that omitting it forces full output, while `project` is tied to the slug of the claim. This adds operational meaning beyond the schema's definitions, making the parameters actionable.

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—checking team decisions and norms before committing to a claim—and differentiates itself from arroway_read, which is for starting work. It clearly identifies the resource (project norms and memory map) and the intended trigger ('in the seconds BEFORE you tell the person something'). This distinguishes it from siblings and leaves no ambiguity about its role.

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 (before telling someone something or proposing a course of action), how often ('many times in one session'), and when not to use it ('When you are starting work on a task, that is arroway_read, and this does not replace it'). It also explains the `since` parameter's role in making repeated calls cheap, covering both usage frequency and cost optimization.

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 reveals significant non-obvious behavior beyond the annotations: the handoff is served at the top of every read until closed, it never expires by clock, it dies in exactly three ways, and age is only informational and never auto-removes. It also mandates writing the essence and warns against session dumps. This adds real behavioral context beyond the readOnly/destructive hints.

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 front-loaded with the trigger condition and is densely informative. It is longer than minimal, but almost every sentence carries a distinct operational rule or constraint needed for correct use. A little tightening is possible, but the length is largely justified by the tool's role as a handoff mechanism with a precise lifecycle.

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 10 parameters, no output schema, and nuanced lifecycle semantics, the description is remarkably complete. It covers when to call, what the handoff does, how it differs from the log, what the essence requirement is, how handoffs end, and how age is treated. It also gives per-field guidance through the schema such that an agent has everything needed to 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?

With schema description coverage at 90%, the structured schema already documents most parameters well. The description adds higher-level operational semantics, such as essence being the default read, supersedes needing explicit reference, read_handles being required reading (with order and refusal behavior), and do_not_redo preventing wasted rework. It does not redefine parameters but enriches how to choose their values.

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 invocation condition ('Call this when you STOP with the task unfinished') and clearly identifies the resource as a handoff of in-flight work. It distinguishes itself from arroway_log by explicitly stating that completed tasks go to the log, so an agent can immediately tell this tool apart from its closest 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?

Usage is explicitly conditional: use it when out of time, blocked, or told to stop, and not for completed tasks, which belong in arroway_log. It also describes the handoff lifecycle—closed by arroway_close, replaced by a superseding pass, or discarded by a person—which helps the agent know when this tool is appropriate versus those siblings.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral detail: include places handles first and cannot be dropped by budget, handoff builds a smaller read, and since's checkpoint behavior is noted. It does not describe the return format, which is a gap given no output schema, but the added context is valuable and consistent 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?

The description is two sentences with no fluff. It front-loads the primary purpose and then provides a compact conditional for full-body recovery. Every clause contributes to understanding, and the structure is 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 the main use cases (default read, include, handoff, since) but omits what the return payload looks like. With no output schema, the agent cannot predict the structure of the response, which is a significant gap for a read tool. It also doesn't define 'Arroway' or the concept of 'authored essence', though these may be assumed from the tool family.

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 each parameter is already documented. The description adds meaning beyond the schema by explaining the budget implications of include and the special behavior of handoff, which are not fully conveyed in the parameter descriptions. This supplements the schema without redundancy.

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 reads Arroway for a project, specifying the verb 'read' and the resource 'Arroway'. It also distinguishes the default behavior (serving authored essence) from the include option to recover full bodies, and the 'BEFORE acting' instruction sets it apart from sibling tools that perform actions.

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 to use this tool before acting on any task related to a project, which is a strong when-to-use cue. It also explains how to request full bodies via include and how to continue a handoff, but it does not explicitly mention alternatives like arroway_search_log for searching, leaving some room for interpretation.

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 non-obvious side effects and server behavior well beyond the minimal annotations: findings are stored as context and never become human-sanctioned norms, revoked findings cannot be rewritten without reconsideration, pinning requires a two-call token comparison, and the server can convert a pin suggestion into a proposal. This gives an agent a realistic model of what the write does and what it costs.

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 long and dense, but nearly every sentence carries a policy constraint or decision rule relevant to correct invocation, and the core purpose is front-loaded. Its main weakness is structural: it is a single wall of text without bullets or section breaks, making it comprehensive rather than elegantly 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?

Combined with the 92%-covered schema and the annotations, the description covers the mandatory kill_condition, active-vs-proposal semantics, finding restrictions, identity routing, and the complete two-call flows for rules and pinning. Nothing essential to making the first or confirmation call correctly appears to be missing, even without an output 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?

The schema already covers 92% of parameters with rich descriptions, so the baseline is satisfied. The description adds orchestration semantics not present in individual field docs: the two-call rule protocol, the pin_suggested/pin_requested_by_human comparison with pin_decision_token, the related_checked/related_check_token requirement, and the treatment='finding' conditions. It does not enumerate all 26 parameters, but the schema compensates for that.

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 opening sentence is a specific verb-plus-resource statement: 'Save a durable memory' with the enumerated types. It immediately distinguishes governed vs finding treatment and special identity semantics, so an agent can understand the operation and its variants without relying on the title alone.

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 clear contextual rules for key branch decisions: when to use treatment='finding' vs governed, when decided_by_human should be true vs false, and where identity memories should be placed. It does not explicitly name sibling tools like arroway_log or arroway_claim as alternatives, so the guidance is internal to this tool rather than cross-tool routing.

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

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

Annotations already declare destructiveHint=true, but the description goes further to clarify that the memory is 'archived, never deleted' and that reads and history are affected, including how the reason is preserved. This adds meaningful nuance beyond the annotation without contradicting it. It does not fully describe all side effects (e.g., impact on dependent items), so 4 rather than 5.

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

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

Three sentences, each earning its place: the first states the core purpose and condition, the second describes the archival behavior, and the third routes to two alternatives. The critical condition is front-loaded, and there is zero 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 moderately complex tool with 4 parameters and no output schema, the description covers the essential decision points: when to use, when not to use, the archival effect, and the required human instruction. It does not mention error conditions or return values, but given the schema richness and the description's clarity, it is sufficiently complete for an agent to invoke correctly. A 5 would require explicit output expectations or error handling, which are not present.

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 has a detailed description (e.g., decided_by_human explains the 'must be true' constraint and the prohibition on inferring). The main tool description adds no extra parameter-specific meaning beyond the schema, so the baseline 3 is appropriate. The description's mention of 'nothing to put in its place' indirectly clarifies the why, but that is already implied in 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 action ('retire'), the resource ('a memory the human already sanctioned'), and the precise condition ('when THEY told you in this conversation to remove it'). It clearly distinguishes from siblings by naming arroway_remember (replacement) and arroway_withdraw (pending proposal), so an agent can disambiguate without reading other 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 gives the when-to-use condition (sanctioned memory, human instruction in this conversation, nothing to replace it) and the when-not-to-use alternatives with the exact tools to call instead (arroway_remember with supersedes_id for corrected versions, arroway_withdraw for pending proposals). This is textbook 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral detail beyond annotations: matching covers the one-line essence and body, results are compact excerpts anchored by project/date/entry, full days are never returned, and the default scope is all accessible projects. No contradictions.

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 front-loaded with the core purpose, then efficiently covers matching behavior, scope, output shape, and a critical caveat. Every sentence earns its place; there is 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 no output schema, the description provides enough for an agent to call it correctly: what is searched, how matches work, how to narrow scope, and the nature of returned excerpts. It does not mention result limits or ordering, a minor gap given the description already explains the essential behavior.

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 both parameters have solid descriptions. The description adds extra semantic value by clarifying the default behavior when 'project' is omitted, that 'query' is a literal case-insensitive term, and that matching applies to both essence and body. This goes beyond the schema baseline.

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

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

The description states a specific verb ('Search') and resource ('recent DATED LOG') and the exact need ('WHERE something was said'). It also distinguishes itself from curated memory and explicitly names arroway_read as a tool it does not replace, making its purpose unmistakable.

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 clear when-to-use context ('when you need to know WHERE something was said'), explains the default scope and how to narrow it with 'project', and warns that it should not replace arroway_read before acting. It does not systematically enumerate sibling alternatives, but the guidance is sufficient for correct 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?

The annotations (readOnlyHint=false, destructiveHint=false) are minimal, so the description carries the burden. It discloses that the tool creates a new project, that the name and scope must be proposed first, that scope is mandatory to prevent cross-contamination, and that the project can later be renamed or deleted. This adds valuable behavioral context beyond the annotations, though it doesn't describe potential side effects beyond creation (e.g., file system changes) — a minor gap.

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

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

The description is a single paragraph but well-structured: it front-loads the core purpose, then gives usage conditions, then step-by-step instructions. It is a bit verbose, but every sentence adds value—no fluff. The key information (when to use, what to do first) is prominent.

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 has 3 required parameters, no output schema, and minimal annotations, the description covers the essential aspects: what it does, when to use it, how to proceed (propose first), and the outcome (project created, can be renamed/killed). It doesn't explain return values, but that's not expected without an output schema. It's sufficiently complete for an agent to call 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?

The schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. However, the description enriches the meaning, especially for scope: 'Scope is mandatory: it is the sentence that stops one circle's material from being written into another.' It also clarifies that name is 'How people will call it' and instructs the agent to propose these to the human, adding practical semantic context 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 clearly states the tool's purpose: 'Open a NEW project in Arroway, when the work at hand has no home.' It uses a specific verb and resource, and provides context that distinguishes it from siblings by emphasizing it's for creating new projects when no existing one fits.

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 conditions: 'Use it when a read refuses an unknown project, or when you notice you have been working on something for a while with nowhere to write it.' It also instructs the agent to propose the name and scope to the human first and only call after agreement, and even tells the agent to say the project can be renamed or killed. This is clear, actionable 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?

Even though annotations already declare destructiveHint=true and idempotentHint=true, the description adds rich behavioral detail: facts are retired automatically when sources are gone, findings are archived or corrected in place, and notes describing timeouts or auth failures are refused. This goes well beyond the structured annotations and clarifies real 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 dense and front-loaded with the core 'bookkeeping, not an errand' rule, and every sentence adds a meaningful constraint or edge case. It is somewhat long and contains run-on sentences, but no sentence is 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?

Given the conditional required-note schema, the destructive potential, and the absence of an output schema, this description covers everything an agent needs: when to invoke, what outcomes mean, what to record in notes, and what automatic consequences follow. The only minor omission is explaining the project parameter, which is likely shared tool 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?

The schema already documents memory, outcome, and note well (75% coverage). The description adds meaning by requiring the #handle from the read, forbidding guessed outcomes, and specifying that source_gone notes must describe actual proof of removal, not mere unavailability. Project is not mentioned, but the schema coverage and overall context make this a minor gap.

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

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

The description leads with a precise verb-resource pair: 'Record what you found when your work ALREADY took you to a memory's source.' It also differentiates itself from siblings by drawing a line against 'verifying memories as a task' and pointing to related tools like arroway_remember and arroway_retire.

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/when-not guidance: only use when you are already at the source, never go verify as a standalone errand, use the read's #handle, and never guess an outcome. It also names the exact follow-up actions for conflicts and source_gone, including when to call arroway_remember with supersedes_id.

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 goes well beyond the annotations: it discloses the non-destructive nature ('kept, marked as withdrawn'), the two-call confirmation flow for another author's proposal, and the consequence of leaving corrections only in personal notes. This is consistent with destructiveHint=false and idempotentHint=true, with no contradiction.

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 long but every sentence carries essential decision-relevant information: scope, exclusions, cross-author behavior, non-deletion semantics, and the follow-up tool. It is front-loaded with the core purpose and then layers edge cases in a readable order with no filler.

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

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

For a tool with four parameters, no output schema, and a subtle non-destructive withdrawal flow, the description covers all important context: when withdrawal is allowed, how the other-author stop works, what happens to the proposal, and what to do with the corrected version. An agent has enough to 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 description coverage is 75%, so the schema already documents why, memory, and other_author_confirmed in detail. The description reinforces the flow around other_author_confirmed but adds little parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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: take back a pending PROPOSAL. It sharply distinguishes this from deletion ('This is not deletion: the proposal is kept, marked as withdrawn') and from other tools like arroway_remember, so an agent can tell exactly what arroway_withdraw is for.

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 when to use it ('pending PROPOSAL that turned out to be wrong'), when not to use it ('a memory the human already sanctioned is theirs, and changing it goes through them'), and what to do instead for durable corrections ('write it with arroway_remember too'). This gives an agent both positive and negative selection criteria.

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