Arroway

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: single-call semantics and the ordering of the returned content (roster and open handoffs first). It does not discuss volume, pagination, or failure modes, so not a 5.

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

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

One sentence, front-loaded with the invocation rule and followed by the expected content. No filler or restatement of the title.

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 carries the burden of hinting at return values, and it does so by naming the roster and open handoffs. For a single optional-parameter read tool this is nearly complete; only the shape/scale of the response is left implicit.

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 schema's own description already explains the default of 2 and when to increase it. The tool description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific retrieval action ('recent work across this person's projects') and even previews the payload ('roster and open handoffs'), which separates it from siblings like arroway_search_log or arroway_read. It stops short of explicitly naming the sibling it replaces, so it is clear but not maximally differentiated.

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?

Timing guidance is unusually explicit: 'Call ONCE at the START of a session, before there is a task.' That tells the agent both when to invoke and that repeated calls are wrong. It does not name an alternative tool or state when not to use it, which keeps it below 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?

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds the substantive behavior that a claim is a non-exclusive mark rather than a lock, so it does not block other claimants. It also discloses the governance rule governing autonomous sessions versus human decisions, which no structured field conveys. The remaining gap is small (no statement on releasing or expiring a claim, which arroway_withdraw presumably handles).

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 tightly packed sentences with the primary instruction front-loaded and the addressing rule following as a qualifier. Nothing is redundant, though the second sentence crams two conditional branches and an autonomy policy into one line, which costs a little readability.

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

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

For a three-parameter, non-destructive write with no output schema, the description covers intent, timing, and authorization boundaries well. It does not say what a successful claim yields or how a claim is later released or superseded, which an agent coordinating with arroway_withdraw or arroway_continue would benefit from knowing.

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 the schema already explains all three fields, including that 'note' is who is taking it and 'handoff' accepts a #handle or full id. The description adds no format, default, or constraint information beyond that. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb and resource: mark that you are taking an open handoff. It also clarifies the conceptual model ('a claim is a mark, never a lock'), which sharpens what the operation actually is. It does not name a sibling tool to contrast with (e.g. arroway_continue or arroway_withdraw), so an agent must infer the boundary from the shared 'arroway_' family.

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

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

Gives explicit timing ('BEFORE working on it') and an explicit decision rule with both branches: if the handoff is addressed to your user, take it; if addressed to someone else, only a human in this conversation can decide, and an autonomous session must leave it. This is a genuine when-to-use / when-not-to-use split with an autonomy constraint, not just implied context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description is consistent with that and adds real context: closure is logged with residue in arroway_log, the note should name what emptied the handoff, and destructive disposal is reserved for a human in the panel. It does not say whether a closed handoff can be reopened or what the response contains, but the safety profile is well covered.

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 core action is front-loaded in the first clause, and no sentence is pure filler. However, the prose is stylized and oblique ("the residue," "what an open handoff exists to fix"), and the third sentence packs three separate rules into one run-on, adding parsing cost for an agent.

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 mutation with annotations and no output schema, the description covers who may close, when, and the required companion logging call. Minor gaps remain: it implies the note is expected even though the schema marks it optional, and it does not state what happens on success or when a handoff is already closed.

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 project, handoff, and note are already documented in the schema. The description adds only marginal meaning, mainly that the note should "name what emptied it" when closing someone else's handoff; the handoff handle and project slug get nothing beyond the schema. Baseline 3 applies 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?

States a specific verb and resource: "Close an open handoff when its work is DONE." It also distinguishes closing from discarding ("discarding a handoff is the human's gesture, in the panel"), which is a useful boundary. It does not name sibling tools such as arroway_retire or arroway_withdraw, so the differentiation is conceptual rather than explicit.

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

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

Gives explicit conditions: close when the work is done and "alongside the arroway_log entry," including someone else's handoff when your work emptied it. It also gives a clear exclusion — a handoff still carrying real work "must never" be closed by a passer-by. The missing piece is routing against the other lifecycle siblings (retire, withdraw, pass) that an agent would need to choose between.

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

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

Annotations already declare readOnly=true, destructive=false and closed-world, and the description adds the meaningful behavioral note that this is optional and non-blocking. It does not say whether repeated calls are idempotent, whether receipts expire, or what happens if the receipt is stale — gaps that matter for an acknowledgment-style call.

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

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

Two short sentences, front-loaded with the action and payload, followed by the optionality caveat. Nothing is padded and no clause is wasted.

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

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

For a two-parameter, closed-world, no-output-schema acknowledgment call, the description covers the essentials: what it does, what it consumes, and that skipping it is safe. Remaining ambiguity (idempotency, stale receipts) is minor at this complexity level.

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%, with both opaque parameters already documented as coming from the read response and the final part. The description only restates their presence ('with its read_id and receipt') and adds no format, lifetime, or sourcing detail beyond the schema, so baseline 3 applies.

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 (acknowledge the final part of a multi-part Arroway read, supplying read_id and receipt) and that it closes the sequence. It is distinguishable from sibling arroway_read by being the terminal acknowledgment step, though it never names arroway_read as its predecessor explicitly.

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

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

Usage is implied rather than stated: an agent infers it should call this after the final part of a multi-part read returns a receipt. The one explicit guideline is an exclusion ('It is not a precondition for working'), which usefully says when not to bother, but there is no 'use when the read response is incomplete' instruction or mention of what to do with siblings like arroway_continue.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral detail: each call returns a new receipt that must be chained into the next call, and completion is signaled by a marker. However, the 'OPTIONAL: the first part already counts as delivered' sentence is ambiguous and leaves the agent unsure whether an extra call is required.

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

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

Two tight sentences with the core purpose and chaining rule front-loaded and no filler. The final 'OPTIONAL' clause is cryptic rather than clarifying and slightly undercuts the otherwise clean structure.

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 carries the return-value burden and does so: it says the response is the next slice plus a new receipt, and that the complete-marked part is terminal. What is missing is only a clear statement of the trigger tool and whether calling continue after the first part is ever necessary.

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 both parameters are opaque ids whose origins are already documented in the schema ('returned by the incomplete arroway_read response', 'returned by the immediately preceding part'). The description restates the same chaining rule without adding format, expiry, or validity details beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Fetch the next part of a read that did not fit') and ties it to the continuation case, which distinguishes it implicitly from arroway_read, the tool that produces the initial (possibly incomplete) read. It never names arroway_read explicitly, so the sibling boundary must be inferred from 'a read that did not fit'.

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 the precondition for use (a preceding read that did not fit, with its read_id and receipt) and gives the stopping condition ('the part marked complete is the last'). It gives no explicit when-not or naming of the producing tool, and the trailing 'OPTIONAL: the first part already counts as delivered' is unclear about whether a follow-up call is needed after part one.

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 the read-only, non-destructive profile, so the description doesn't need to repeat it. It does add real behavioral content beyond them: only sanctioned, live memories are included, FINDINGS are excluded by rule, and the response reports how many findings stayed behind — useful for predicting the result of the call.

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, front-loaded with the purpose, no filler. The second sentence is slightly riddling ('a FINDING never was one, so findings stay and the answer tells you how many did') but it still carries the exclusion rule and the return hint compactly.

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?

Read-only annotations plus full schema coverage carry most of the burden, and the description hints the response reports excluded findings. What remains unclear is the shape of the pack itself — whether it is returned inline or materialized, and what fields it contains — which matters for an export tool with no 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?

Schema description coverage is 100%, so each of the four parameters is already documented (name, topic filter, project slug, description). The description adds conceptual context about what is exported but does not clarify how 'topic' narrows the set or what the pack-level 'name'/'description' fields control, so baseline 3 applies.

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 ('Export what a project has DECIDED, as a pack for another project') and narrows scope to decided/sanctioned memories rather than all content. It never names the obvious sibling arroway_import as its counterpart, so the differentiation is implied rather than explicit.

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?

'As a pack for another project' implies the transfer-between-projects scenario, which gives the agent a usable trigger. There is no explicit when-not guidance, no mention of arroway_import as the reverse operation, and no stated prerequisites (e.g. project must exist, must have sanctioned memories).

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 past the annotations by disclosing two real behavioral traits: every imported item is downgraded to a proposal regardless of what the pack asserts, and the import is atomic — any malformed part aborts the whole thing. It stops short of noting permission requirements, pack size limits, or how proposals are surfaced afterward.

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

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

Three short sentences, front-loaded with the action, then the proposal guarantee, then the failure mode. No filler and the emphasis caps land on the two facts an agent must not get wrong.

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 tool with a nested pack object and no output schema, the description covers origin, side effects, and failure semantics adequately. It could say what an agent gets back (created proposal count or identifiers) so it can confirm the import, but 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 the schema already explains that `pack` is the document itself (no URL fetching) and that `project` should be checked against the `arroway_catch_up` roster if guessed. The description adds nothing param-specific, so the baseline 3 applies.

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 (import a memory pack into a project) and names its sibling `arroway_export` as the producing counterpart, so the round-trip pairing is unambiguous. The caps on INTO and PROPOSAL frame the scope 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?

The link to `arroway_export` tells the agent where packs come from, and the proposal framing tells it this is the ingestion path rather than `arroway_remember`. It never states when NOT to use it, e.g. that single memories should go through `arroway_remember` or that existing pinned items are untouched by this route.

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

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

The annotations already establish a non-read-only, non-destructive, closed-world operation. The description adds durability and lifecycle-linkage context, but it does not explain the side effects of listing a memory in fulfills, whether log entries can be revised, or what the call returns.

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 compact sentences front-load the purpose and then cover the two special recording rules. There is no filler or repeated background material, and each sentence has a distinct operational function.

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?

Together with the richly documented schema, the description supplies enough purpose, scope, and special parameter guidance for correct invocation. The absence of an output schema makes the missing return-behavior information more noticeable, and sibling differentiation and the consequences of fulfills remain underexplained.

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%, but the description still adds meaningful cross-field semantics: essence is effectively mandatory despite not being schema-required, with a narrow frozen-catalog exception. It also reinforces the condition for populating fulfills, although that condition largely repeats 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?

“Record the durable residue of a COMPLETED task” gives a specific verb, resource, and scope, and the following clause clarifies that the record should prevent later duplication of work. It does not explicitly distinguish this tool from siblings such as arroway_remember or arroway_close.

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 clearly says to use it for a completed task and gives conditional guidance for essence and fulfills. It lacks explicit routing guidance for when another sibling should be used instead, or whether logging is required as part of a particular task-completion 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?

Annotations only say this is a non-read-only, non-destructive, closed-world tool; the description adds the crucial fact that memory moves are pending proposals requiring the person's review while log-entry moves are immediate and leave text unchanged. It also supplies the rationale ("moving changes who sees it"). What remains undisclosed is the effect on the source project and what the call returns for each mode.

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

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

Three short sentences, zero filler, with the most consequential fact (proposal vs. immediate) front-loaded right after the purpose statement.

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 four-parameter mutation tool with full schema coverage and no output schema, the description covers the essential behavioral divergence between modes. It stops short of describing the outcome of each call, which an agent might want to know when confirming a move succeeded or is pending.

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 all four parameters carry their own descriptions, including the meaning of why for memory moves. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ("Move something to the project it belongs in") and then immediately resolves the vague "something" into the two resources it covers: a memory or a log entry. The two-mode split makes it unambiguous what gets moved, though the opening line alone is less precise than the two that follow.

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 separates the two cases an agent must choose between: memory moves are proposed and wait for human review, log entries move immediately. It does not name alternatives such as creating a new entry with arroway_remember or when a move should be avoided, so there is no exclusion 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 this is a safe read (readOnlyHint true, destructiveHint false), so the bar is lower. The description does add non-obvious context: that it returns an index/map rather than full content, and that a follow-up arroway_read does not get cheaper. However, the shape of the returned map is left opaque, and 'in the project's language' handling is only implied.

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

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

It is short, but front-loading is muddled: the imperative 'Call in the seconds BEFORE...' delays the actual return statement, and the ALL-CAPS 'AND THEN A MAP' interrupt reads as emphasis rather than structure. The sentences are compressed to the point of ambiguity.

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?

There is no output schema, so the description must carry return semantics; it says decisions plus a map of titles and handles but never explains what a handle is or how to use the map afterwards. For a read tool with three parameters it is workable but leaves the agent guessing about the response layout.

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 all three parameters are already documented, and the baseline is 3. The description adds one genuine usage cue for `draft` (pass text you intend to publish), but says nothing extra about `since` beyond what the schema states about checkpoints and suppressed standing rules.

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 concrete return: what is already decided plus 'a MAP of the titles and handles'. That is specific enough to tell it apart from arroway_read, which is explicitly described as returning a mapped item 'in full'. The phrasing is idiosyncratic ('Call in the seconds', 'A MAP') but the resource and output are identifiable.

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 timing ('BEFORE you tell the person something or propose a course of action') and a separate trigger ('Before publishing text for others, pass it as draft'). It also names the alternative arroway_read and states the exact selection rule: use it 'to be sure, never to pay less'.

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 say this is a non-read-only, non-destructive, closed-world write; the description adds the genuinely useful behavioral fact that the handoff persists at the top of every read until closed, which no annotation conveys. It also adds a hard authoring rule about essence that is not derivable from structured fields. It stops short of naming what is returned (the #handle needed for superseding or closing) or what permissions/state are required to close 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?

Two sentences, front-loaded with the call trigger, with no filler. The parenthetical about a 'frozen catalog without that field' is unexplained jargon that costs the reader a beat, which keeps it below 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 10-parameter mutation tool with no output schema, the description covers the essential decision (use this vs. arroway_log) and the persistence behavior of what it creates. It leaves two gaps an agent would care about: what the call returns (presumably a handle) and how the handoff is subsequently closed, plus the meaning of the 'frozen catalog' carve-out.

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 earns above that by adding meaning the schema does not carry, notably that essence is authoring-mandatory even though it is absent from the required list, with a narrow exemption for a frozen catalog. It does not clarify how supersedes, read_handles, or addressed_to interact in practice, so it is not exhaustive.

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 concrete effect: calling it 'leaves a HANDOFF served at the top of every read until someone closes it,' which tells an agent exactly what artifact is created and how it behaves. It also explicitly separates this tool from the sibling that handles the opposite case ('a completed task ends in arroway_log instead'), so the agent can choose between the two without opening either 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 trigger condition is stated precisely: 'Call when you STOP with the task unfinished.' The exclusion and alternative are also given in the same sentence, routing completed work to arroway_log. It also states the lifecycle exit condition (until someone closes it), which is the implicit alternative to using this tool at all.

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, non-destructive and closed-world, so the safety profile is covered. The description adds the pre-action sequencing rule and a note that include recovers a full object body, but says nothing about what a read returns, how 'since' checkpoints behave, or what happens when handles are out of scope.

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 the most important instruction (read before acting) front-loaded, and no filler. Slightly compressed to the point of terseness — '#handle' and 'object's full body' assume domain familiarity.

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 five-parameter tool with no output schema, the description leaves the return value entirely unexplained, and 'Read Arroway' never states what Arroway's contents are (rules, handoffs, objects). The pre-action guidance and include hint cover invocation, but an agent cannot predict what comes back.

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 every parameter already carries its own documentation, making 3 the baseline. The description's mention of '#handle in include' largely restates the schema's 'full body you need; they come first and others fall out' rather than adding format or precedence detail.

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 Arroway for a project') plus the timing constraint 'BEFORE acting on any task related to it.' It is clear enough to distinguish a full project read from siblings like arroway_search_log or arroway_log, though it does not name any of the 18 siblings to sharpen the boundary.

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

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

Gives a clear when-to-use trigger ('BEFORE acting on any task related to it'), which is genuinely useful sequencing guidance. However, it offers no when-not conditions and no alternatives among the many sibling tools (e.g. catch_up, continue, search_log), so the agent must infer routing on its own.

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 declare a non-read-only, non-destructive write. The description goes further by disclosing the proposal/sanctioned distinction, the fact that a proposal imposes a review cost on the person, and the read-visibility asymmetry between findings and sanctioned memories. It does not explain the multi-call token flow or what the tool returns, which limits it to a 4.

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, front-loaded with the gating condition before the type taxonomy and scoping rules. No filler. Slight cost from jargon used before definition ('a finding') and a compressed final sentence that reads as an appended caveat.

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 26-parameter write tool with a multi-phase protocol, the description covers the conceptual bar for saving but says nothing about the two-call flow implied by token parameters (pin_decision_token, related_check_token, related_checked), nor about pin ceilings or what the call returns. Those details live only in per-parameter schema text, so an agent can recover them, but the description itself is thin relative to 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?

Schema description coverage is 100%, so the baseline is 3. The description does add genuine meaning for the 'identity' type, specifying that a user's circle belongs in their personal project and a business's people in that business's project — a placement rule absent from the enum's 'Kind of memory' text. The parenthetical type list otherwise just restates the enum, so it does not rise above 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?

States a specific verb and resource ('Save a durable memory') and enumerates the six memory kinds, then adds the decisive gating rule: only when it would change a DIFFERENT task. That distinguishes it from logging or verification siblings without naming them. It stops short of explicitly contrasting with arroway_norms or arroway_log, so a 4 rather than a 5.

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 a hard inclusion test ('only when it would change a DIFFERENT task') and explains the consequence when the person has not sanctioned it in the current conversation ('it is a PROPOSAL'). It also carves out an explicit exclusion: 'A finding cannot replace a sanctioned memory.' It never names a sibling to use instead when the bar is not met, which keeps it out of 5 territory.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the real precondition — human instruction and no replacement — which is genuinely useful context beyond the annotations. It still does not say whether retirement is reversible, what happens to the retired memory, or what the person sees afterwards.

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 filler, with the eligibility condition front-loaded and the two routing alternatives packed into the second sentence.

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 four-parameter destructive tool with no output schema, the definition covers the decisive questions: who must authorise it, when it is the wrong tool, and where to go instead. The remaining gap is what retirement actually does to the memory and whether it can be undone, which matters for a destructive operation.

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

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

Schema description coverage is 100%, so all four parameters including the decided_by_human constraint and the #handle convention are already documented in the schema. The description adds no further parameter-level meaning, which is the baseline case.

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 plus a narrowly qualified resource ('Retire a SANCTIONED memory'), and immediately names two sibling tools that cover the neighbouring cases, so an agent can separate this from arroway_remember and arroway_withdraw without opening any 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?

Gives an explicit trigger condition ('the person told you to remove it and nothing replaces it') and two explicit alternatives with their selecting conditions: a corrected version routes to arroway_remember supersedes_id, an agent's own pending proposal routes to arroway_withdraw.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still adds real behavior beyond that: the search is literal, not semantic, and is limited to the 'recent' log rather than full history. It does not say how recent, how results are ordered or capped, or whether matches are substring or token based, which is the remaining gap for an agent deciding if results are exhaustive.

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

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

Two short sentences, front-loaded with the verb and resource, with the memory/log disambiguation placed second because it is secondary. Every clause carries information; nothing is padding.

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 read-only tool with full schema coverage, annotations, and no output schema, the description covers purpose, scope, and matching mode adequately. The one loose end is the undefined 'recent' window, which matters for judging whether results are complete, but it is a minor omission rather than a blocking one.

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%: query is documented as a literal, case-insensitive term up to 200 chars, and project as an optional slug whose omission searches all projects. The description restates rather than extends this, adding no syntax, matching, or slug-format detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb (find), the resource (dated log), and the scope (one project or all of them), and contrasts the target of the search: 'searches what happened, not curated memory.' That distinguishes it conceptually from the memory-oriented siblings such as arroway_remember and arroway_read without needing to open a 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 phrase 'not curated memory' tells the agent when to pick this over the memory tools, and 'in one project or all of them' encodes the project-vs-global choice. It stops short of naming an alternative tool explicitly or stating when not to use it, so it is clear context rather than full 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 annotations (readOnly=false, destructive=false), it discloses that update rewrites scope, that the slug is immutable on rename, that ownership is required, that invite can return a checkout link for a team plan, and that parameters should be confirmed with the person first. Notably, rewriting an existing scope is a lossy overwrite that destructiveHint=false does not signal, and the description only half-compensates by saying "rewrites its scope".

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?

Roughly three compact sentences, front-loaded with the primary create action, then the update and invite modes. Slight terseness in "it needs slug, name and scope" and "Propose them to the person FIRST" reads as clipped, but nothing is padded.

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 five parameters, no output schema, and annotations already covering safety, the description covers every parameter's intent plus the precondition of confirming values with the person. It omits failure behavior (e.g. slug collision on create, update against an unowned project), which is the main remaining gap.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description still adds real meaning the schema lacks: update implies the slug stays fixed, and invite's email produces a checkout link when a team plan is required.

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?

"Open a NEW project" gives a specific verb and resource, and the description explicitly separates the create path from the in-tool update and invite modes. It never names or contrasts a sibling tool (e.g. arroway_move or arroway_claim), so an agent comparing this against the other 17 arroway_* tools gets no help from the text 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?

"when the work has no home" is a clear use condition, and update has its own trigger ("when the person asks or the scope is wrong"). It also prescribes an interaction pattern: propose slug, name, and scope to the person FIRST. No when-not guidance or alternative tool is offered, which keeps it off 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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the description must add specifics about what gets destroyed. It does: source_gone archives the memory and a conflict is corrected in place, which tells the agent the write is consequential. It doesn't clarify whether these are reversible or what confirmation is 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 short sentences with the key constraint ('never go verifying memories as a task') front-loaded, and the alternative routing placed immediately after. A few fragments ('On a FINDING', 'A conflicting one') are terse to the point of ambiguity, but nothing is padding.

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

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

No output schema exists, so the description carries the burden of explaining consequences, and it covers the destructive outcomes (archive on source_gone, in-place correction on conflict). It leaves the 'matches' path and any response/confirmation behavior unstated, which is a small but real gap for a mutation tool.

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 enum meanings and note requirement are already documented in structured data. The description adds only marginal semantics, mostly restating that a conflicting source leads to a correction via arroway_remember. 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: recording what a memory's source says. It distinguishes itself from arroway_remember by assigning corrections to that sibling. The title 'Record what the source says' reinforces the purpose, though phrases like 'On a FINDING' are undefined and slightly obscure the exact outcome set.

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 when-not guidance is given: 'never go verifying memories as a task', only record when work already took you there. It also names the alternative for the conflict case (arroway_remember). It stops short of spelling out what to do for a plain 'matches' outcome or how this interacts with arroway_read / arroway_complete_read.

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 declare the generic non-readOnly/non-destructive profile; the description adds genuinely new behavior: only pending proposals are affected, sanctioned memories are out of scope, and a companion write may be needed afterward. It does not explain reversibility, whether the withdrawn handle is freed, or the two-step other_author_confirmed confirmation flow that the schema implies.

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

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

Three short sentences, front-loaded with the action and scope, then the exclusion, then the recommended follow-up. No filler or restatement of the title.

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 four-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, exclusion, and the follow-up write. It leaves unexplained the two-call confirmation path and the post-withdrawal state of the proposal.

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 all four parameters (why, memory, project, other_author_confirmed) are already documented, including the 'second call only' confirmation semantics. The description adds nothing parameter-specific beyond the schema, so the baseline 3 applies.

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

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

States a concrete verb and resource: 'Take back a pending PROPOSAL,' with the qualifier 'pending' bounding the scope. It also carves out an exclusion ('Not for sanctioned memories'), which separates it from lifecycle siblings like arroway_retire, though it never names which tool handles the sanctioned 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?

Gives an explicit trigger ('turned out wrong, usually because the person corrected you'), an explicit exclusion ('Not for sanctioned memories'), and a follow-up routing to arroway_remember when the correction is durable. No guidance on what to do instead for sanctioned memories, which is the only gap.

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