TeamShared

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

With no annotations provided, the description carries the full burden, and it delivers real behavioral detail: it returns '{changed: false}' and does not comment when the picture is unchanged, and it writes to a 'create-once' work item rather than creating a new one each run. This exceeds what the schema alone reveals, though it does not cover overwrite vs. append or auth requirements.

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 tightly written and front-loaded: purpose in the first sentence, artifact details, no-op return behavior, and bot-side scheduling each in their own clause. Every sentence earns its place with zero 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?

An output schema exists, so return values are covered. The description explains what the file contains, where it attaches, the no-op behavior, and the scheduling model. The only notable gap is what happens on a changed picture (presumably it does comment), which is implied but not stated.

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 both parameters are already documented. The description adds minimal parameter-specific meaning beyond the schema — it reinforces that slug targets a Person/Organization rather than a Contact or Deal, but introduces no new syntax or formatting guidance. The 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: 'Writes one shared file (stakeholders, initiative, objections, last evidence, next review, five-line brief) attached as an artifact on a create-once account work item.' This is concrete enough to distinguish it from generic siblings like file_create, work_create, and storage_attach, which have no weekly-brief semantics.

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 provides scoping context ('for one strategic Person or Organization', 'Weekly schedule is bot-side') and the schema notes slug is 'not Contact or Deal', which narrows usage. However, it never names an alternative or states an explicit when-not-to-use condition, leaving the agent to infer that this is a scheduled bot task rather than a manually invoked tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a mutating action ('Cancel') but does not explain consequences such as whether the run is irreversibly stopped, whether resources are cleaned up, whether confirmation is needed, or what happens to in-flight work. The description adds no behavioral context beyond the verb itself.

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 front-loaded sentence with no wasted words. It is concise and immediately identifiable as an action statement. It loses one point because the imprecise 'active' qualifier is not clarified, but overall it is well-sized.

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 tool has three optional parameters and an output schema, but no annotations and no usage context. The description does not explain how to choose between run_id and cursor_agent_id, what 'active' means in this context, or what side effects cancellation has. For a mutating tool, this is incomplete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides, and the schema adequately describes run_id, cursor_agent_id, and agent. No additional insight is needed, but none is offered.

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 ('Cancel') and resource ('TeamShared Cloud Agent run'), making the basic action clear. However, the qualifier 'active' is slightly misleading because the schema allows specifying a run_id or cursor_agent_id for a particular run, not necessarily the active one. Still, the core purpose is unambiguous and distinct from sibling agent_run_* tools.

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

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

There is no guidance on when to use this tool versus alternatives like agent_run_status, agent_run_followup, or agent_run_hitl_decide. It does not describe prerequisites, side effects to check before cancelling, or situations where cancellation would be appropriate. The agent is left to infer usage from the tool name alone.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that the run uses the seat's recorded model, that a model swap is surfaced as model_substitution, and that the run's tool narrowing and agent record are preserved. It still omits permission/auth requirements and whether execution is asynchronous, but the behavioral disclosure is well above baseline.

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 lines with the action and target front-loaded and no filler. The middle sentence packs some jargon ('model_substitution') but each clause adds substantive behavior, so only minor tightening is possible.

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?

An output schema exists, so return values need not be explained, and the description covers the two non-obvious behaviors (model substitution reporting, tool-narrowing persistence) for a no-annotation mutation-style tool. Missing only auth/async semantics, which keeps it short of a 5.

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 agent, prompt, run_id, and cursor_agent_id are already documented in the schema. The description adds no parameter-level syntax or format detail beyond noting the run must already exist, 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: 'Enqueue a follow-up prompt on an existing TeamShared Cloud Agent.' The word 'follow-up' plus 'existing' cleanly separates it from agent_run_start, and it names that sibling directly, so an agent can route 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 prerequisite (an already-existing cloud agent run) is implied by 'existing' and the analogy to agent_run_start, but there is no explicit when-to-use/when-not or clear alternative selection between this and agent_run_start. Usage is inferable but not spelled out.

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?

There are no annotations, so the description carries the full behavioral disclosure burden. It states that a run is resumed and that a human has decided, but it does not disclose the consequences of that decision: approving may execute the previously gated call, rejecting may deny it, and editing changes the arguments before execution. For a mutation tool, this is a meaningful 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?

One short, front-loaded sentence that states the action first and the trigger second. There is no filler, and it is easy for an agent to scan and understand in one pass.

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 a full schema, an output schema, and no nested objects, the description does not need to restate parameters or return values. However, the absence of any behavioral/safety context, no annotations, and no statement about what approve/reject/edit causes, leaves the context only partially complete for a tool that gates a destructive call.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the required reason for reject and the arguments field for edit. The prose adds no parameter-level detail beyond the phrase 'gated tool call,' which gives context but does not add semantics 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 names a specific action ('Resume'), a specific resource ('a paused agent run'), and the exact trigger ('after a human decides on a gated tool call'). This is not a tautology and clearly differentiates the tool from siblings such as agent_run_cancel, agent_run_status, and agent_run_followup.

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 a clear condition for use: a paused agent run that is waiting on a human decision about a gated tool call. It does not explicitly spell out when not to use it or name alternatives like request_gated_approval or agent_run_followup, so it stops short of exhaustive 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states a read-only action ('List') but does not mention pagination, ordering, auth requirements, or any side effects. For a list operation, it is reasonable to assume safety, but the description fails to explicitly confirm that, leaving the agent to infer behavior.

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?

A single, front-loaded sentence that states the purpose without any fluff. It efficiently communicates the essential action and scope, making it easy for an agent to parse quickly. There is no redundant information or unnecessary detail.

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 simplicity of a list operation and the presence of an output schema, the description is largely sufficient. It mentions the key scope ('in this org') and the entity type, which is enough for basic use. However, it could briefly note that results are paginated via limit/offset to fully prepare the agent, but this is a minor 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?

The description adds no parameter-specific meaning beyond what the schema already provides. Two of the four parameters (work_id and cursor_agent_id) have schema descriptions, while limit and offset are self-explanatory with defaults and bounds. With 50% schema coverage, the description could have clarified usage, but it does not, leaving the agent to rely solely on schema hints.

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 a specific verb ('List') and a well-defined resource ('TeamShared Cloud Agent runs in this org'). It differentiates from sibling list tools like process_run_list and work_list by naming the exact entity type. The scope 'in this org' adds precision, leaving no ambiguity about what is being listed.

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 no explicit guidance on when to use this tool versus alternatives. While the name and description make it obvious this is for listing agent runs, it does not mention exclusions or point to other tools for different list scenarios. Usage is implied rather than stated, which is acceptable but not proactive.

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?

No annotations are present, so the description carries the full burden and does so richly: single-active-run concurrency, busy status, capped profile prepending, playbook injection order, model substitution with model_substitution={requested, model, reason}, and agent_slug inheritance with agent.inherited reporting. This is well beyond what a bare tool name conveys.

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?

Front-loaded and appropriately sized for a 12-param tool, with the key disambiguation up front. Some sentences are awkwardly terse ('Unset slug or omitted work_id: no playbook inject.') and layers of parentheticals reduce scanability, but little 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?

An output schema exists, so return values need not be explained, and the description covers the concurrency model, injection behavior, substitution, and inheritance an agent needs to invoke this correctly. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuinely non-redundant semantics: how model= is substituted when the router would refuse it, how agent_slug= inherits model/tools (explicit model wins, explicit tools can only narrow), and the ephemeral-vs-durable memory of nested runs.

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?

Opens with a specific verb+resource ('Start a TeamShared Cloud Agent (router + FastMCP)') and immediately disambiguates with 'Not a Cursor VM.' An agent can distinguish this from agent_run_cancel/followup/status siblings without opening the schema.

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

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

It gives situational constraints (one active run per work item; a busy run returns status=busy; playbook/profile injection rules) but never names an alternative tool or states when to prefer agent_run_followup or agent_run_status instead. Usage is implied rather than routed.

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

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

With no annotations available, the description carries full behavioral disclosure. 'Read' indicates a non-mutating operation, which is helpful, but it does not describe behavior when both ids are omitted or invalid, whether it can return partial/in-progress state, or any latency/auth considerations.

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?

A single sentence with no filler: it states the action, resource, and scope efficiently. Every word contributes to understanding the tool's purpose.

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 output schema covers return values, and the schema covers parameter semantics, but the description itself lacks guidance on when to use this tool and how the optional ids interact. For a tool with two optional parameters, the absence of usage context leaves a noticeable 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 description coverage is 100%, and the schema already documents both parameters, including default behavior for cursor_agent_id. The description adds no parameter-level meaning, 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 uses a specific verb ('Read'), a resource ('TeamShared Cloud Agent run'), and qualifies it as 'latest status', making the operation clear. It is distinguishable from siblings like agent_run_list or agent_run_cancel, though it does not explicitly name the alternative it is not.

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

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

The description gives no guidance on when to use this tool versus agent_run_list or agent_run_start, and no exclusions or conditions. It also does not explain how to choose between run_id and cursor_agent_id, leaving usage context entirely to the agent.

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

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

With no annotations, the description carries the full burden and excels: it discloses that it writes a shared file attached as an artifact on a create-once work item, returns {changed: false} and does not comment when unchanged, and notes the schedule is bot-side. These are concrete behavioral traits beyond the schema.

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 exceptionally concise and well-structured: two sentences front-load the purpose, then add key behavioral details. Every sentence earns its place, with no filler or repetition.

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 core behavior, side effects, and scheduling, which is strong for a tool with a single optional parameter and an output schema. It lacks explicit prerequisites (e.g., org binding) and return behavior when changed, but those are minor given the output schema exists and the tool is simple.

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 only parameter 'agent' is fully described in the schema ('Override agent identity'), and the description adds no further meaning. Since schema coverage is 100%, the baseline of 3 is appropriate; the description does not enhance parameter understanding.

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 it produces an 'Org attention briefing' from 'open work, project status, and dream', giving a specific verb and resource. It also clarifies the data source ('Work is the signal — not Slack or email'). However, it does not name or contrast any sibling tools, so an agent might not easily distinguish it from similar briefing tools like account_brief.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The only usage hint is that the hourly schedule is bot-side, implying it is not intended for manual invocation, but no when-to-use or when-not-to-use instructions are provided, and no alternative tools are mentioned.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It merely restates the schema without describing side effects, return values, error conditions, or the fact that calling arbitrary tools may have destructive consequences. This is a significant transparency 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 exactly two sentences, front-loaded with the primary action and followed by a usage hint. Every word earns its place, with no redundancy or fluff.

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

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

The tool is simple, but with no output schema and no annotations, the description could have mentioned that the tool returns the called tool's output or that invalid names will error. The core functionality is clear, but some behavioral expectations are missing, so it is minimally viable rather than complete.

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

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

Schema coverage is 100%, with both parameters described. The description adds little beyond the schema, repeating 'by name with the given arguments' without explaining how arguments map to the called tool's parameters. 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 clearly states the action: 'Call a tool by name with the given arguments,' which specifies the verb and resource. It also differentiates from search_tools by noting the tool is for executing discovered tools, but it does not explicitly distinguish from the sibling executar_lote, so it falls short of 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?

The description provides clear usage context: 'Use this to execute tools discovered via search_tools.' This tells the agent when the tool is appropriate, but it does not mention exclusions or alternatives, so it is not a full 5.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds useful traits such as self-healing expired sessions, the response's session_id being authoritative, and the returned fields, but it omits side effects of close (queueing distillation, clearing the state pointer) and any permission or failure behavior.

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 short sentences front-load the one-line summary, then give the replacement relationship, behavioral caveat, and return shape. 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?

Given the 8-parameter schema with 100% coverage and an output schema, the description provides the essential selection and behavioral context: when to use it, what it replaces, self-healing behavior, and authoritative session_id. The schema fills the remaining parameter and return-value details, so nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description only maps summary/facts/close to 'assistant summary + durable writes + optional close' without adding new syntax or format details beyond the schema.

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

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

The opening line defines the tool as a 'Turn-end batch' combining assistant summary, durable writes, and optional close, and the second sentence names the exact memory_* sequence it replaces. This makes its purpose and distinction from sibling memory tools immediately clear.

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 positions the tool as the end-of-turn replacement for memory_session_append + memory_remember (+ memory_session_close + memory_state_set), so an agent knows when to prefer it. It does not explicitly state when not to use it, such as for mid-turn appends, so it lacks full 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?

With no annotations, the description must disclose side effects and behavior. It does mention that originals are stored in CCR (Redis) with ref= markers for retrieval, and that it 'Always runs' and thresholds are tunable. However, it doesn't describe the return value, potential data loss, or any permissions needed. It gives some behavioral transparency but leaves gaps.

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 concise, with the key purpose in the first sentence. It provides necessary details in two more sentences without excess. The structure front-loads the purpose and then elaborates on behavior and configuration. No fluff.

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

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

The tool has a single parameter with good schema coverage and an output schema (not shown). The description explains the purpose and storage side effect but doesn't detail the return format (presumably in output schema), nor does it mention any prerequisites like Redis availability or error conditions. Given it's a straightforward compression tool with one input, it's fairly complete but could state expected output behavior more explicitly.

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

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

The schema description already covers the 'messages' parameter well, stating it's OpenAI-style chat messages and that user messages are preserved while long tool/assistant/system blocks shrink. Since schema coverage is 100%, the description adds only minor reinforcement (mentions JSON tool outputs and logs) but doesn't significantly extend 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?

The description clearly states it compresses a prompt payload before sending to an LLM, and specifies what it shrinks (JSON tool outputs, logs, long text). It distinguishes itself from other context tools by focusing on compression and storage of originals. It's not a tautology and gives a specific verb-resource pairing.

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 says 'Always runs' but does not provide explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. It hints at a companion tool (context_retrieve) but doesn't tell the agent when to choose this over other context tools like context_normalize or context_prepare. The 'always runs' suggests it might be automatic, which is a usage signal but not a clear directive.

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

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

With no annotations, the description carries the full burden, and it discloses real behavioral traits: it trims recall-style payloads, shrinks large JSON/logs, and stores originals in CCR when compressed. This goes beyond the schema and gives agents a clear sense of side effects and preservation behavior.

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

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

The description is compact and front-loaded with the core purpose; the second sentence adds valuable usage and side-effect context. 'Strip, clean, and compress' is slightly redundant, and 'CCR' is not expanded, but the overall 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?

For a simple two-parameter tool with an output schema, the description covers purpose, usage boundaries, processing behavior, and a notable side effect. Nothing essential is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds context about target tools (Shell, Grep) but no additional parameter-level syntax or formatting details, matching the baseline for full schema coverage.

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 action ('Strip, clean, and compress') on a specific resource ('non-teamshared tool output') and states the intended use ('for agent context'). It also distinguishes this tool from the middleware path for teamshared tools, so an agent can tell it apart from siblings like context_compress.

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 guidance: call this for Shell, Grep, or other harness tools, and prefer MCP middleware for teamshared tools. It names exclusions and alternatives, leaving little to inference.

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

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

No annotations are present, so the description carries the burden. It discloses the pipeline stages and return payload, and it clarifies that teamshared normalization is already handled elsewhere. But it does not state whether session append persists state, whether compression discards messages, or any side effects or permissions, which matters for a tool that mutates a working session.

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-load the purpose and returns, then give the usage context and scope. No filler; the pipeline arrow notation is efficient and every sentence earns its place.

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

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

The description covers purpose, return values, and usage timing, and the output schema handles return structure. But with eight parameters and siblings like context_compress, context_normalize, and memory_assemble_context, it does not fully disambiguate when to choose this tool over those, nor does it mention the messages-vs-prompt requirement or side effects.

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 8 parameters. The description adds no parameter-level detail beyond the schema; it only restates the concepts of session append, compression, and enrichment. 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 concrete pipeline ('session append → compress incoming history → enrich') and lists the exact return fields, so an agent can tell this is a pre-LLM context assembly tool. It gestures at differentiation by saying it 'covers the rest of the prompt' after middleware normalizes teamshared responses, but it never names a sibling such as context_compress or memory_assemble_context.

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

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

It gives an explicit trigger: 'Use before sending a turn to your LLM when you want teamshared to shrink tool bloat and inject recall.' It also clarifies scope relative to server-side middleware. However, it provides no exclusions or named alternatives for cases like standalone compression (context_compress) or memory-only assembly (memory_assemble_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?

No annotations are provided, so the description correctly carries the full burden. It explicitly discloses the read-only nature ('Read-only'), the return unit (micro-USD with the conversion factor spelled out), and the roadmap context that writes are not yet available. This provides meaningful behavioral context beyond what structured metadata would cover.

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 zero waste. The first sentence front-loads the core purpose, and the second adds the essential unit detail and read-only disclosure. Every word earns its place; there is no filler or repetition.

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

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

For a zero-parameter, read-only tool with an output schema covering the return value, the description covers all that's needed: what it does, the unit of measurement, the scope, and the read-only constraint. The only minor gap is not describing edge cases (e.g., behavior with zero balance), which is a negligible concern for such a simple 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?

The tool has zero parameters, and the rubric grants a baseline of 4 for this case since there is nothing to document. Schema coverage is trivially complete at 100% with an empty object. The description correctly needs no parameter explanation.

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: 'Return the current org's prepaid router credit balance.' This is unambiguous and clearly distinguishes itself from all sibling tools, none of which deal with credits or balances. The scope ('current org') and object ('prepaid router credit') are precisely defined.

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 purpose sentence inherently signals when to use it — when an agent needs the org's credit balance. The 'Read-only — no write tool yet (credit purchases land in Phase 2 via Stripe)' line clarifies what it is NOT (a purchase/credit tool), providing useful exclusionary context even though no direct alternative tool is named.

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

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

With no annotations provided, the description carries the full burden. It discloses the output format (Mermaid), the mode ('generated'), the limitation (not architecture recovery), the fact that TeamShared is not a git host, and the version restriction. It does not explicitly mention side effects like permissions or failure behavior, but the read-and-store nature is conveyed. This is strong but not 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?

The description is moderately long but well-structured, with the core purpose front-loaded and supplementary details (source reading, metadata, alternatives) following logically. Each sentence adds information; no filler. It is slightly verbose but remains efficient for a tool with 8 parameters.

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

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

Given the tool's complexity (8 optional params, output schema present), the description covers the main workflow, version constraints, and usage context. It explains the source inputs and the attach mechanism. It does not detail the exact output structure, but that is delegated to the output schema. Overall, it provides enough for an agent to decide when and how 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the github parameter's optionality when work_id already carries a github pointer, and by noting default behaviors for view and title. These clarifications help avoid misuse, making it a 4.

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 ('Sketch') and resource ('a teamshared.diagram/v1 from GitHub manifests'), and immediately distinguishes it from the sibling diagram_sync (refresh) and file_create (v2 authoring). It clearly states what it does and what it is not (architecture recovery), leaving 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 this tool (to generate a v1 diagram from GitHub manifests) and when not to (for the layered v2 scene, use file_create with content_format='diagram'). It also references diagram_sync for later refresh, providing clear routing among alternatives.

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

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

With no annotations provided, the description carries the full disclosure burden and does so exceptionally: no-op on matching commit/content hash, refusal of authored mode unless force=true, forced versions becoming mode=generated, and scene inputs returning changed=false with reason='scene'. These are concrete behavioral traits beyond the schema.

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

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

The description is compact, front-loaded with the primary action, and every sentence carries distinct information: main behavior, no-op condition, forced-authored behavior, manual invocation, and scene edge case. There is no filler or repetition.

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

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

Given the tool's moderate complexity and the existence of an output schema, the description covers the essential operational context: when it does nothing, when it refuses, what happens under force, and how scene diagrams are handled. The lack of annotations is compensated by unusually thorough behavioral detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the authored/generated mode interaction and what force actually produces ('new version is mode=generated'). It does not elaborate on ref or agent, but those are already well documented 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?

The description opens with a specific verb and resource: 'Re-fetch mapped GitHub paths and append a version if they changed.' This clearly conveys the operation and outcome. It does not explicitly name or contrast a sibling like diagram_generate, so it stops short of full sibling differentiation.

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 invocation trigger: 'No webhook or periodic worker — call this when you want a refresh.' It also clarifies when the tool refuses (authored mode without force) and when it no-ops. It does not name alternative tools, so it misses the explicit alternatives part of the top score.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose a key behavioral trait: 'History is never mutated,' which is important for an append operation. However, it does not mention other behaviors such as idempotency, duplicate handling, or failure semantics, leaving some gaps.

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 short sentences with no wasted words. The core operation is front-loaded, and the behavioral guarantee is stated immediately after, making it easy to parse quickly.

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

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

For a simple append operation with full schema coverage and an output schema, the description is largely complete. It states the core behavior and the most important guarantee (history immutability). It could be slightly stronger with usage context, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The tool description adds no new parameter-level meaning beyond what is already present, which matches the baseline for full schema coverage.

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 identifies the action and resource: 'Append one event to a stream.' It is specific enough to distinguish from read-only siblings like event_list, though it does not explicitly differentiate from other append-like tools such as memory_session_append.

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 implies the tool is for recording a new event in a stream and notes that history is never mutated, which gives some context for when it is appropriate. However, it provides no explicit guidance on when to choose this tool over alternatives like event_list or memory_session_append.

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

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

With no annotations provided, the description carries the behavioral burden. It does disclose two useful traits: events are append-only and results are in timeline order. However, it omits other behavioral details like pagination behavior, the meaning of the export flag, or what happens when stream_id is null.

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 sentence with no filler. 'Append-only' and 'timeline order' are both high-signal qualifiers, and the core purpose is front-loaded.

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

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

The output schema and partial parameter descriptions reduce the burden on the tool description. Still, the description leaves important context unstated: stream_id is optional, export changes the response shape, and there is no mention of when to prefer this over related list tools.

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 67% (4 of 6 parameters described), but the description itself adds no parameter semantics. The uncovered parameters (limit, offset) are simple, but the description does not compensate for the moderate coverage gap or explain the stream filter in terms of the schema's stream_id.

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 ('List') and resource ('append-only events for a stream'), with an ordering qualifier ('timeline order'). It is clear enough to be distinguished from the write-oriented sibling event_append, though it does not explicitly name alternatives or clarify that stream_id is optional.

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 no guidance on when to use this tool versus alternatives such as process_run_events or event_append. There are no explicit when-to-use conditions, exclusions, or alternative tool references.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the operation is append-only, that the source of truth is evidence.attached on run:{id}, and that a second attach to the same slot supersedes the previous pointer. It does not mention auth or error cases, but the core behavioral contract is transparent.

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 efficient sentences: the first states the action and core mechanism, the second explains the source-of-truth, supersession, and preference guidance. Every clause adds value, and the purpose is front-loaded.

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

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

For a 9-parameter tool with an output schema, the description covers the essential usage context, alternatives, and behavioral nuances. It does not mention potential errors or validation, but the output schema likely handles that. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds context around slot/pointer supersession but does not elaborate on individual parameter formats beyond what the schema provides. 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 clearly states a specific verb (attach) and resource (evidence to a Process run) and explains the append-only mechanism. It also distinguishes from alternatives like file_create auto-attach and direct case-file mutation, making the tool's purpose unambiguous.

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 provides explicit guidance: agents should prefer this tool (or file_create with work_id) over mutating a case-file row, and it explains the supersession behavior for same-slot attaches. This tells the agent exactly when to use it and what to avoid, leaving no ambiguity about alternatives.

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

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

With no annotations, the description carries the full burden. It discloses the read-only nature ('Read'), explains the projection over events, and details the merging behavior for work/project pass-throughs. It does not mention side effects (expected none for a read) or access-control requirements, but the disclosed behavior is sufficient for safe invocation.

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, each earning its place. The core purpose is front-loaded in the first sentence, and the parameter guidance is compact and direct. No fluff or repetition.

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 tool with an output schema, the description covers the operation, the parameters, and the key merging behavior. It does not mention pagination or limits, but these are unlikely to be critical for a spine read and are partially covered by the output schema signal. Adequate 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful value beyond the schema: it clarifies that exactly one ID should be passed ('Pass one of'), and it explains that work_id and project_id fold evidence from linked runs, which interprets their otherwise generic schema descriptions. This exceeds 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 precise verb and resource: 'Read the case-file spine' and lists the states it covers (required/received/missing/superseded). This clearly distinguishes it from write-type siblings like evidence_attach and event-listing tools like event_list, so an agent can tell it apart without opening the schema.

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

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

The description gives explicit parameter usage ('Pass one of run_id, work_id, or project_id') but does not state when to prefer this over alternatives, nor does it give negative guidance like 'use evidence_attach to add evidence' or 'use event_list for raw events'. The purpose implies when to use it, but explicit routeing is missing.

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

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

With no annotations, the description partially carries the behavioral burden by disclosing that this is an 'append-only event' and that it folds into missing/received/superseded states. However, it does not explain failure modes, permissions, idempotency, or what happens when evidence is declared for a non-existent or already-completed run.

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 short and the main purpose is front-loaded in the first sentence. The second sentence is dense but informative, though the phrase 'folded with received attachments' is somewhat compressed and may require domain knowledge to parse.

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 moderate complexity, full schema coverage, and presence of an output schema, the description covers the core operation but leaves usage guidance and the meaning of the folding behavior implicit. An agent could call it correctly, but not with full confidence about when it should be chosen over evidence_attach.

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 six parameters and their meanings. The description adds no parameter-level detail beyond what the schema provides, so the baseline score 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?

Uses a specific verb and resource: 'Declare required evidence on a Process run' immediately identifies the operation and target. The phrase 'append-only event' plus the contrast with sibling tools like evidence_attach and evidence_get makes its role in the evidence lifecycle clear.

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 intent is implied by the action word 'Declare' and by the sibling context, but the description never explicitly says when to use this tool instead of evidence_attach or evidence_get. No exclusions or alternative selection criteria are given, so an agent must infer the boundary between requiring evidence and attaching evidence.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses default privacy, the need for explicit publishing, immutable version behavior, attachment semantics, diagram format details, caps, and strict schema validation ('Unknown keys are rejected').

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 densely informative, front-loads the core purpose, and uses structured paragraphs and bulleted variants. Every major sentence adds operational value, especially the diagram schema details that would otherwise require external documentation.

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 complex creation tool with 6 parameters and multiple content formats, the description covers defaults, publishing workflow, versioning, attachments, diagram schemas, limits, and validation behavior. An agent has enough context to invoke the tool correctly; the output schema covers return-value needs.

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?

Though schema coverage is 100%, the description substantially enriches parameter meaning. It explains how content_format=diagram maps to two distinct diagram schemas, defines node/edge requirements, caps, and clarifies that work_id/project_id attach to the same shared_files row with kind=artifact for projects.

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

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

The first sentence names a specific verb, resource, and scope: 'Create a new versioned shared file in the caller's org.' It clearly distinguishes the tool from siblings like file_update and file_publish by emphasizing creation, versioning, and the caller's org.

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 routes to alternatives: call file_publish for public share URLs, and notes that file_update is the operation that creates new immutable version rows. It also gives attachment guidance for work_id and project_id, making the tool's role in the workflow unambiguous.

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

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

With no annotations, the description carries the full burden and does well: it discloses the version/content/public_url return shape and warns that content is the full uncompressed latest version. It omits auth requirements or rate limits, but the behavioral picture is otherwise strong.

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?

Front-loaded with the core action, then supporting semantics. The 'This result is not compressed: a shortened file is not the file' line is a slightly verbose warning but earns its place as a truncation guard.

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?

An output schema exists so return values need not be explained, yet the description usefully explains them anyway. It covers the fetched resource, version round-trip, and conditional fields, leaving little ambiguous for a single-param read 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?

Only one parameter (file_id), and schema coverage is 100%, so the schema already documents it. The description adds no parameter-level detail beyond the schema, which is the expected baseline when the schema does the work.

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+resource ('Fetch a shared file with its latest version content') and clarifies output semantics. It implicitly differentiates from the file_list/file_update siblings by tying the returned version to a subsequent edit, though it never names a sibling directly.

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?

Provides real conditional guidance: pass the returned version as expected_version on file_update when editing a shared file. This tells the agent where this fits in the workflow, but it does not state when to prefer file_get over file_list or other alternatives.

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

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

With no annotations, the description carries full behavioral burden and does so well: it specifies ordering, included fields (public_url, slug, share_token), when fields are present ('when published'), the 'Archived files stay joined but are omitted' exclusion, filter precedence, and the special work_id/Storage artifact behavior.

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 purpose is front-loaded in the first sentence, and the remaining paragraphs add dense, non-redundant detail. Every sentence contributes meaningful guidance—order, fields, filters, alternatives, precedence, and exclusions—without 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 output schema exists, the description covers everything else an agent needs: scope, ordering, filter semantics, field inclusion conditions, archive behavior, precedence, and the relationship to storage_list. The only uncovered param, limit, is fully specified in the schema.

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

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

Schema coverage is 75%, so baseline is 3, but the description adds real value beyond the schema: a concrete query example, the work_id transcript-join meaning, the project_id document listing behavior, and explicit filter precedence. Only 'limit' receives no added semantic context, but the schema already documents its constraints and default.

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

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

The first sentence states a specific verb, resource, and scope: 'List active shared files in the caller's org, newest update first.' This clearly identifies what the tool does and is distinguishable from siblings like storage_list, file_get, and file_create.

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 guidance is explicit: 'Use query to find a file by title without listing everything', 'Pass work_id to list documents + the agent transcript', and 'storage_list is canonical for every Storage join including blobs'. It even clarifies precedence ('project_id wins if both filters are set'), giving the agent concrete routing rules.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals idempotency, eager pushing of rendered HTML to the Railway bucket, URL structure with a fallback, and access restrictions—all beyond what a schema would convey. It does not cover error handling (e.g., what happens if the file does not exist) or rate limits, but the core behaviors are transparent and align with the operation's nature.

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 a single sentence but well-structured: the first line states the core purpose, the second details idempotency and output mechanics, and the third addresses access control. Every sentence adds substantive value; there is no fluff. The pacing is efficient, though it could be tightened by moving the Railway bucket detail to the output schema or a separate note.

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

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

Given the tool's complexity (multiple output URLs, gating, idempotency) and that an output schema exists, the description covers the most critical runtime context: what the agent will receive (both URLs), that it is safe to call repeatedly, and the exact gate alternative. It does not describe preconditions (e.g., file must exist and be in a publishable state) or error scenarios, but the provided information is sufficient for correct invocation in the common case.

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

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

Schema description coverage is 100%, so the file_id parameter is already fully documented in the schema ('File UUID to publish'). The tool description adds no additional semantic detail about the parameter (e.g., format, validation, or edge cases). Since the schema fully covers the parameter, the baseline score of 3 is appropriate—the description does not need to repeat schema information.

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

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

The description opens with a precise action: 'Publish a shared file: generate the public share token + slug and URL.' It clearly identifies the resource (shared file) and the output (token, slug, URL). It also distinguishes itself from other publishing tools (e.g., storage_publish) by detailing the specific token/slug mechanism and the /s/ URL format. This leaves no ambiguity about what the tool accomplishes.

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 states when to use this tool and when not to, naming the alternative: 'Agent seats (org tsk_ / agent_run) are refused — call request_gated_approval(gate="publish") instead. Console humans (ts_session) still publish.' It also implies usage context through idempotency, informing agents that repeated calls are safe and return existing tokens. This is explicit, actionable guidance that completely removes guesswork.

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

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

With no annotations, the description carries the full burden and does so richly: concurrency semantics (mismatch writes nothing, returns status=conflict), versioning invariant (old versions never mutated, append at prior-max-plus-one), and the side effect of eager mirroring to the Railway bucket for published files. This is exactly the behavioral context an agent needs.

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?

Front-loaded with the core action, then the conditional and side-effect details. Every sentence adds 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 mutation tool with no annotations, it covers conflict behavior, versioning invariants, and publish side effects. An output schema exists, so return-value details are not needed in the description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the intent behind expected_version (guarding against a concurrent writer) and points to file_get as the source of the version value, which goes beyond the schema's mechanical conflict description.

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

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

States a specific verb and resource ('Append a new version to an existing shared file'), which cleanly separates it from file_create (new file) and file_get (read). An agent can identify the operation and target without opening the schema.

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

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

Gives explicit conditional guidance for the key parameter: pass version from file_get when editing a shared file to avoid clobbering a concurrent writer, omit expected_version to append unconditionally. It does not explicitly contrast with file_create for new files, so the routing is implied rather than named.

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

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

With no annotations, the description carries full burdencents for behavioral disclosure. It thoroughly describes the script's lifecycle (reads file, POSTs, prints id/URL, deletes itself on success), token security (single-use, ~10 min expiry), and update-mode side effects (preserves title/slug/share_token, re-publishes mirror). This goes well beyond a simple API call description.

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 somewhat long but well-structured with a main paragraph, a code-execution block, and a dedicated 'Update mode' section. Information is front-loaded with the core purpose, and every sentence contributes to usage or behavior. Slight verbosity in the script walkthrough prevents a perfect 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 complex tool with 9 parameters and an output schema, the description covers all essential aspects: when to use, full script execution flow, return values, update-mode semantics, and token lifecycle. Output schema already documents return fields, so the description needn't repeat them. No significant missing information 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 baseline is 3. The description adds contextual nuance like 'title ignored in update mode' and the script's behavior related to publish, but these are also present in the schema's field descriptions. The description doesn't add significant new parameter semantics beyond what the schema already documents.

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 ('Get... push'), a resource ('a local file into a shared file'), and explicitly distinguishes itself from file_create/file_update by specifying its use case for large files that don't fit inline. This clearly separates it from 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 states when to use this tool ('For large local HTML/Markdown files that don't fit inline in file_create/file_update') and provides a specific alternative path for updating ('pass file_id'). It also labels update mode as 'the supported way to push a new version of a large file,' giving clear routing guidance.

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

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

With no annotations provided, the description carries the full behavioral burden and handles it well. It discloses that optional dependencies report 'disabled' without degrading overall status, that the call is cheap, and that it is safe to poll frequently. These are meaningful behavioral traits beyond the bare input/output contract.

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

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

The description is compact and well-structured: purpose first, followed by return shape, component semantics, failure behavior, and operational guidance. Every sentence adds useful information, and none repeats the input schema or annotations.

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

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

For a zero-parameter health probe with an output schema present, the description is complete. It explains the return structure, defines the ambiguous 'semantic' component, clarifies optional dependency behavior, and gives explicit polling guidance. 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?

The tool has zero parameters, so there is no parameter documentation burden. The description focuses on the response shape and component meanings instead, which is the appropriate use of description space given the empty input schema.

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

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

The description opens with 'Liveness + dependency probe', which clearly states the tool's function, and then specifies exactly what it returns: status, version, and component health. This is distinct from the many sibling tools because it is explicitly the healthcheck/status probe rather than an account, memory, or work operation.

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 usage context: 'Always cheap; safe to poll on a 10s interval. Used by Docker healthcheck and the /health HTTP route.' This tells an agent when polling is appropriate, though it does not explicitly compare against alternatives such as `version` or state when not to use this tool.

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

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

With no annotations provided, the description carries the full behavioral burden and does substantial work: it discloses side effects (emails a 6-digit code), session-wide statefulness (later tools run as that person), the headless-only constraint, and a security rule (do not store code/token). It stops short of covering failure/retry behavior or expiry, but the key stateful and side-effectful traits are clearly surfaced.

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

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

Every sentence earns its place: purpose and constraint in line one, routing guidance in line two, and a numbered invocation sequence. The most important qualifier (last-resort, headless-only) is front-loaded, and the step numbering makes the multi-call flow easy to follow without 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?

Given an output schema exists (so return values need not be spelled out) and 100% parameter coverage, the description completes the picture with the flow states, the conditional org branch, and post-auth session behavior. The only minor gap is failure mode handling (e.g., wrong code), but nothing needed to invoke the tool correctly across its documented states is missing.

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

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

Schema description coverage is 100%, so the parameter descriptions already explain email, code, and org_id semantics including the code_sent and need_org statuses. The description adds orchestration context (which order to pass parameters in), but per-parameter meaning is fully carried by the schema, matching the baseline-3 case for high coverage.

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?

Opens with a specific verb+resource statement: 'email + OTP bind for this MCP session (headless only).' The 'last-resort' qualifier and 'headless only' constraint make its role unmistakable, and among the sibling list (org_bind, health, version) there is no competing auth tool, so an agent can identify it 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?

Explicitly tells the agent when NOT to call it ('Do not call this as the first hop'), names the preferred alternatives (Cursor Connect, 'tsk_' header), and gives a concrete condition for when it is appropriate ('When the host has no token'). The numbered 3-step flow with the conditional need_org branch leaves no ambiguity about invocation order.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It openly states the side effect (get-or-create), the org scope, and the exact slug derivation for harness vs. cloud agents. It does not say whether existing profiles are silently returned or updated, but 'Get-or-create' communicates the core non-destructive intent.

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

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

The description is compact and front-loaded with the most important information: the operation and its resource. The slugging rules and read-alternative pointer are each one clause with no filler or repetition.

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

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

Given the output schema handles return values and the schema covers all 7 optional parameters, the description is largely complete. It misses a small but useful pointer to memory_agent_set for explicit updates, but the get-or-create semantics and read alternatives cover the main decision paths.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how parameters map to the agent slug (name to agent-<label>, cursor_agent_id to agent-<cursor_agent_id>), which is not derivable from the individual parameter descriptions alone.

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

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

The description opens with a precise verb phrase 'Get-or-create' and a specific resource ('this org's ontology Agent + shared memory profile'), so an agent knows exactly what the tool does. The slugging convention distinguishes it from read-only siblings like memory_agent_get and memory_entity_view, and the 'ensure' semantics are immediately clear.

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 actionable context: use this tool to get-or-create an agent profile, and read the profile with memory_agent_get or memory_entity_view. It does not explicitly say when to use memory_agent_set or memory_agent_list instead, but the get-or-create framing and named read alternatives provide decent 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Read' and 'org-shared ontology memory,' which implies a safe read operation, but it does not disclose what happens when multiple identifiers are provided, whether it errors on ambiguous inputs, or what the output structure is despite an output schema existing. It also does not clarify auth or sharing semantics beyond 'org-shared.' For a read tool with zero annotation coverage, this is a significant 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, clear sentence with no filler, front-loading the core action and resource. It is concise and to the point, though it could add a little more context without becoming verbose.

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 tool with an output schema and fully documented parameters, the description is mostly sufficient, but it lacks behavioral guidance on parameter combinations and tool-specific nuances. The output schema covers return values, so that's handled. However, a clearer usage distinction from memory_agent_list or memory_recall would complete the picture. Minimum viable but not fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (name, slug, cursor_agent_id) with their roles. The description adds minimal extra meaning beyond saying 'read memory' and doesn't explain how the parameters interact (e.g., 'omit together with slug/id to fetch the caller' is already in the schema). Baseline 3 is appropriate since the description doesn't contradict or significantly extend 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?

Description clearly states the action ('Read') and resource ('another agent's (or your own) org-shared ontology memory'), which is specific enough. It is distinct from siblings like memory_agent_list (which likely lists memories) and memory_agent_ensure/set (which write), though it doesn't explicitly name them.

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 implies usage for reading ontology memory, and the parameter docs hint that omitting identifiers fetches the caller, giving a sense of when to use defaults. However, it does not explicitly say when to prefer this over siblings like memory_recall or memory_agent_list, nor does it provide exclusions or routing guidance. This is implied by the resource name but not stated.

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?

No annotations exist, so the description carries the behavioral disclosure burden. 'List' conveys that this is a read-only operation and 'in this org' sets the scope, but nothing is mentioned about ordering, pagination behavior, or any side effects. These are minor for a simple list tool, but the description adds little beyond what the name and schema already imply.

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?

A single front-loaded sentence with no filler: the verb, resource, and scope come first, and the parenthetical about agent references earns its place by clarifying why the list matters. Nothing extraneous is present.

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, read-only list tool with no required parameters and an existing output schema, the description covers the essential context: what is being listed and in which org. It does not explain the runtime filter or result ordering, but the schema already documents runtime and the output schema covers return structure, so the gaps 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 description coverage is only 33% (runtime is described as 'harness or cloud'), and the description provides zero parameter guidance. Limit and offset are left to their self-evident names and defaults; since coverage is below 50%, the description should have compensated, but it does not. The agent must infer the pagination filter semantics from the schema alone.

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 uses a specific verb ('List'), an explicit resource ('Agent ontology memories'), and a scope ('in this org'), while adding the functional note that other agents can reference them. This clearly distinguishes it from sibling tools like memory_agent_get (single fetch) and memory_agent_set (write).

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 context is clear: use this to get a directory of Agent ontology memories for the current org, especially when you need identifiers other agents can reference. It does not explicitly enumerate when not to use it or name alternatives, but the listing semantics and org scope are sufficient for an agent to select it over the single-entity 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?

With no annotations, the description must carry behavioral disclosure; it does communicate that this is a mutating, upsert-style operation (replace or create). It does not cover permission requirements, reversibility, or consequences for existing memory, so transparency is adequate but incomplete.

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 compact sentence states the action, scope, and key edge case (creates if needed) with no filler. The parenthetical carries meaningful behavioral information without bloating the description.

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 mutation tool with an output schema, this is minimally viable: schema covers parameters and return values, and the description covers the essential operation. It still lacks guidance on alternatives and exclusions (e.g., private vs. org-shared scope boundary is only in the schema), so it is not fully complete.

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

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

Schema description coverage is 100%, so the structured parameter docs already explain every argument. The tool description adds no parameter-level detail beyond the core concept, which is fine under the baseline for full schema coverage.

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 ('Replace') with a clear resource ('an agent's org-shared memory profile') and adds the upsert behavior ('creates the entity if needed'). This distinguishes it from read-only siblings like memory_agent_get and memory_agent_list, and from ensure-style semantics, making the tool's role unambiguous.

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 implies when to use it: when an agent's shared memory profile should be replaced or created. However, it does not explicitly state when not to use it or name alternatives such as memory_agent_ensure, leaving the routing decision partly to inference.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool recalls across pillars in parallel, ranks and packs results, and returns specific fields. However, it does not explicitly state whether it is read-only or has side effects. The 'recall' language implies read-only, but without annotation support, a clear statement about non-mutation would be ideal. This minor gap prevents a perfect score.

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 well-structured with a clear first sentence stating the main action, followed by a detailed explanation of the recall mechanism and a usage note. It is somewhat verbose but every sentence contributes meaning. It is front-loaded with the core purpose, making it easy for an agent to grasp quickly. Slightly tighter wording could earn a 5, but it remains 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 tool's core function, usage timing, and return fields (rendered, tokens_used, counts_by_pillar, records). Given that an output schema exists, the return format is likely specified there. The description does not discuss error conditions or prerequisites, but for a context-assembly tool with 6 parameters and optional graph support, the provided information is sufficient for correct invocation. A mention of potential failure modes would make it more complete.

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

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

The schema has 100% parameter description coverage, so the baseline is 3. The tool description does not add semantic value beyond what the schema already provides. It mentions the 'task' indirectly and refers to the pack, but does not elaborate on parameters like 'repo', 'github', or 'open_files' in a way that would improve understanding. It meets the baseline but does not exceed it.

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: 'Assemble one token-budgeted, cited context pack for a task.' It clearly defines the output as a sectioned markdown bundle and differentiates itself from sibling tools by naming the alternative serial calls (memory_recall, memory_procedure_get, memory_graph_related). The purpose is unambiguous and distinguishable.

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

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

Explicitly states when to use the tool: 'Use this once at the start of a task instead of issuing serial memory_recall / memory_procedure_get / memory_graph_related calls.' This directly instructs the agent on the appropriate invocation context and names the alternatives to avoid, which is exemplary usage 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?

With no annotations, the description carries the behavioral burden. It discloses the output ordering (oldest-first), the fact that it returns a new opaque cursor, and the limitation that it is not a full checkpoint. It implies a read operation (returns delta), but does not explicitly state read-only or describe side effects. It adds useful context beyond the schema (e.g., resume-handoff, current-truth), so it is strong but not perfect.

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

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

The description is three sentences, front-loaded with the core purpose. It packs a clear purpose, return behavior, usage guidance, and a limitation without any fluff. Every sentence contributes to orientation or selection.

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 presence of an output schema covers return format. The description covers why and when to use the tool, plus a key limitation. It does not explain the effect of filters (kind, repo, pillar) but those are fully documented in the schema. For a tool of this complexity, this is adequately complete, though it could mention that only memory_items are returned for pillar filtering, which is in the schema but not the description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add semantic detail about individual parameters beyond what the schema already provides. It mentions 'opaque cursor' and 'current-truth' conceptually, but these are also covered in the schema descriptions. No extra value added.

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 a specific action: providing a resume-handoff delta of durable org memory since an opaque cursor, returning current-truth rows newer than the cursor. It explicitly distinguishes itself from memory_recall for keyword search, making its purpose unambiguous to an agent.

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 direct usage instruction: 'Use this to continue another session's work' and contrasts with 'use memory_recall for keyword search.' It also flags a limitation ('Not a full checkpoint/context pack'), telling the agent when not to use it. This is explicit and actionable.

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

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

With no annotations the description carries the full burden, and it delivers meaningful traits: fixed section order, a verbatim constraints lead when standing rules exist, 'shared brain: no agent filter', and cursor-based incremental resume. It stops short of an explicit safety/read-only statement, but the behavior disclosed is substantial.

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?

Front-loaded with the purpose and scoping, then progressively more detail; each sentence (return shape, build source, cursor, alternatives) earns its place. Slightly dense but well-ordered rather than 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?

Covers return shape, cursor semantics, budget behavior, and sibling alternatives; since an output schema exists the field enumeration is somewhat redundant, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, and the description largely reinforces rather than extends that. It adds a little on cursor chaining and the budget cap, but not enough to move above the high-coverage baseline of 3.

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 ('bounded resume pack for an agent starting or resuming work') and enumerates exactly what the single call returns. It distinguishes itself from siblings by naming memory_recall (further search) and memory_assemble_context (task-driven pack), so an agent can route without opening schemas.

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

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

Explicit when-to-use ('starting or resuming work'), explicit alternative routing ('use memory_recall for further search', 'memory_assemble_context for a task-driven pack'), and explicit cursor lifecycle ('persist cursor and pass it next time to receive only newer changes').

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

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

With no annotations provided, the description carries the behavioral burden and does well by disclosing the found=false fallback when no report was written and clarifying that the content is stored as an ordinary semantic memory page. It does not cover auth, rate limits, or explicit read-only guarantees, but for a parameterless report getter the disclosed behavior is adequate.

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

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

The description is compact and front-loaded, with the key purpose in the first sentence and supporting behavioral details in the next two. Every sentence adds distinct value: scope, return behavior, and relationship to memory_recall. 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?

Given the tool has no parameters, an output schema is present, and the behavior is simple read-only retrieval, the description covers everything needed to call it correctly. It explains what is returned, what happens when nothing was written, and how the note relates to the broader memory system.

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 tool has zero parameters and the schema description coverage is 100%, so there is no parameter information for the description to meaningfully add. The baseline for zero-parameter tools is 4, and the description appropriately focuses on behavior rather than parameter 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?

The description opens with a specific verb-object pair: 'Latest nightly dream report for this org (what changed overnight)', clearly identifying the resource and scope. It further distinguishes itself by noting the report is also a normal semantic memory page that memory_recall can find, which positions this tool as the dedicated status view rather than a generic recall tool.

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

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

The description provides clear context: use this when you need the most recent nightly dream/change report for the org. It also mentions that the same note is discoverable via memory_recall, which indirectly signals a related alternative, though it does not explicitly state when to prefer one over the other.

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?

There are no annotations, so the description is the only safety/behavior signal. 'Roll up' strongly implies a non-mutating aggregation, but the description does not explicitly state read-only behavior, required permissions, freshness, or pagination; the tool name 'view' helps but is not a substitute for annotation coverage.

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

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

A single sentence with no filler; the action, data sources, and scope are all present and front-loaded. Nothing in the description is redundant with the input 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 one-parameter tool with a rich output schema, the description says enough about what the caller gets (aggregation of four data categories) to invoke it correctly. It omits deeper selection guidance, but that is already scored under usage guidelines.

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 slug parameter is already fully documented as a wiki topic slug or ontology entity slug. The description adds no additional parameter-level meaning beyond reinforcing that the operation is scoped to a single entity.

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 concrete action ('Roll up') and names the exact resource types included (wiki, memories, graph neighbors, work) plus the entity scope. It conveys a broad aggregated entity view, though it does not explicitly contrast with siblings like memory_recall or memory_assemble_context.

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 'for one entity' implies the intended use case: get an aggregated view of a single entity's related data. However, it never describes when to prefer this over the many memory-looking siblings, nor does it state exclusions or prerequisites beyond having a slug.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the operation is append-only, writes to the memory:{id} stream, and leaves the memory body unchanged, which is important context beyond the tool's name. It could add details about duplicate votes or failure behavior, but the output schema covers return shape.

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

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

The description is compact and front-loaded: the first sentence states the action, and the second paragraph adds only essential behavioral guardrails. There is no filler, redundant schema restatement, or vague introductory language.

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 4-parameter tool with a full output schema and no annotations, the description covers what the tool does, how it behaves, and which sibling tools handle related cases. An agent has enough information to invoke it correctly without guessing about side effects.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description: vote is an enum with semantics, memory_id is traced to a prior memory_recall, and note/agent are optional overrides. The description reinforces that memory_id refers to a recalled memory but adds little new parameter-level 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?

The description opens with 'Record +1/-1 feedback on a recalled memory id', naming a specific action, object, and allowed value range. It also distinguishes itself from nearby memory tools by stating it does not modify the memory body and by pointing corrections and rewrites to memory_remember, memory_forget, and memory_skill_feedback.

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

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

The description explicitly tells the agent when this tool is not the right choice: corrections belong on memory_remember/memory_forget, and skill/playbook rewrites belong on memory_skill_feedback. It clearly implies use after a memory_recall hit when the goal is only to record a positive or negative vote.

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

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

With no annotations, the description carries the full burden and mostly succeeds: it discloses newest-first ordering, prefix-match semantics, 'current-truth' filtering (implying superseded memories are excluded), the shared-brain scope ('no agent filter'), and the provenance/matched_paths payload. It does not mention required permissions, rate limits, or pagination behavior beyond the schema's k.

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 leading sentence is front-loaded with the core purpose and ordering, followed by tight, evidence-dense detail. The parenthetical examples earn their space, though the middle sentence is somewhat run-on and could be split for 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?

An output schema exists, so return-value explanation is not strictly required, and the description still usefully describes the provenance block and metadata.matched_paths. For a read-only, 4-param lookup the coverage is nearly complete, missing only explicit statements of permission requirements and whether the operation is side-effect free.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond it: it explains the prefix/directory matching rule for paths and how repo-sharing interacts with tag matching, and ties the tag format back to memory_remember(paths=). The k, repo, and github behaviors are largely left to the schema.

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

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

States a specific verb and resource ('returns current-truth memories tagged path:<p>') and pins down the exact matching semantics, including that a directory matches files under it and that 'src/billing' will not match 'src/billing2'. An agent can distinguish this from memory_recall (keyword search) 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?

Explicitly frames the tool as 'An exact path lookup, not search' and names the alternative ('use memory_recall for keywords'), giving both when-to-use and when-not. It also names memory_remember(paths=) as the producer of the data being looked up, closing the loop on the 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?

No annotations are provided, so the description carries the full burden and does so: it discloses the org binding, required ``memory:read`` permission, share/scope reach, trust labelling for unattended agents, read-only nature, and how superseded records surface (``retired_at``/``replacement_id``). It also explains that ``missing`` deliberately merges several failure causes, which prevents the agent misreading the response.

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?

Front-loaded with the core purpose and tightly written, with each sentence adding distinct information. It is dense to the point of being slightly hard to parse on first read (stacked clauses about scope reach and trust labelling), which keeps it out of the top band.

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 single-parameter lookup with an output schema present, this covers everything an agent needs: prerequisites, permissions, id provenance, the shape of ``records``/``missing``, and stale-record handling. Nothing material is missing.

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

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

Schema coverage is 100% and the parameter description already covers the 25-item cap and the source scan, so the baseline is 3. The description goes further by telling the agent which id types are NOT valid inputs here, which is genuine semantic guidance beyond the schema.

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

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

States a specific verb and resource ("Full memory records by id") and immediately positions it relative to the sibling it complements ("the second step after a summary recall"). An agent can distinguish this from memory_recall 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?

Explicitly names the precondition (ids obtained from a memory_recall summary scan) and the exclusions ("Ids of skills, playbooks and work come from their own tools, not this one"). Both when-to-use and when-not-to-use are covered.

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?

No annotations are provided, so the description carries the full burden. It discloses one meaningful behavioral trait: the tool returns a version that feeds optimistic-concurrency checks on memory_playbook_set. It does not state that this is a read-only fetch, nor any auth/permission requirements or side effects — so the disclosure is partial for an un-annotated tool.

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?

Tight, front-loaded two-sentence structure with no filler; the alias is stated first and the actionable version tip follows. It is appropriately sized, though the brevity comes at the cost of stating the actual purpose.

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?

An output schema exists, so return values need not be described, yet the description still usefully flags version. For an un-annotated read tool with three parameters, the definition is adequate but leaves the core operation and any authorization model implicit, and it points to a tool (memory_procedure_get) that is not among the siblings.

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 name, version, and expand_skills are already documented in the schema. The description adds only the connection between the returned version and expected_version, which is useful but not parameter-level semantics beyond the schema. 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 identifies the tool as an alias for memory_procedure_get and notes it returns version, but it never states plainly what the tool actually does (retrieve a playbook/procedure by name). An agent unfamiliar with the aliased tool must infer the core purpose; the fetch semantics are implied by the 'get' suffix and the alias reference, not spelled out.

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 downstream guidance — pass the returned version as expected_version on memory_playbook_set when editing a shared playbook — which is genuinely useful context. However, it offers no guidance on when to choose this over siblings like memory_playbooks_list, memory_skill_get, or memory_recall, and no conditions for using the version or expand_skills parameters.

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?

No annotations are provided, so the description carries the full disclosure burden. It only notes that it 'forwards expected_version', a concurrency/versioning hint the schema already documents in detail, and says nothing about mutation semantics, ownership inheritance, or consequences of a version conflict.

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 fragments with no wasted words, so it is not bloated. However, the extreme terseness is under-specification rather than effective conciseness for a tool with nine parameters.

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 tool has 9 parameters and an output schema (so return values need not be explained), but the description still omits what a playbook is, how writes behave, and how it relates to the visible memory_playbook_get/list siblings. Referring to a non-sibling tool leaves an agent unable to fully understand the 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% and expected_version is extensively documented in the schema itself, so the baseline is 3. The description adds no parameter meaning beyond what the schema already states.

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 only asserts that this tool is an alias for 'memory_procedure_set', which is not even present in the sibling list, so the agent cannot resolve what the underlying operation does. It never states the verb+resource (create/update a playbook) in its own terms, making it effectively a restatement of identity rather than a purpose.

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

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

There is no guidance on when to choose this over memory_playbook_get, memory_playbooks_list, or memory_skill_set, nor any prerequisites or conditions. The alias note implies interchangeability but gives no decision criteria for an agent selecting among the memory_* 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?

No annotations are provided, and the description discloses no behavioral traits (read-only, destructive, permissions, etc.). 'Alias' gives no information beyond implying identical behavior to memory_procedures_list, which is itself unspecified.

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

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

The description is extremely short but not effectively concise—it omits essential information rather than presenting a focused, structured explanation. It is under-specified rather than efficient.

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

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

For a tool with 4 parameters and an output schema, the description provides almost no context: no functionality, no usage scenarios, no differentiation from siblings. It is far from complete.

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

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

The schema documents only tag and include_body (50% coverage), leaving limit and offset undescribed. The description adds nothing about parameters, failing to compensate for the schema 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 only says 'Alias for memory_procedures_list' without stating what the tool actually does. It implies shared functionality but leaves the agent to look up the aliased tool, so the purpose is not directly clarified.

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

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

There is zero guidance on when to use this tool versus the aliased memory_procedures_list or any of the many other memory_* siblings. The description does not mention context, conditions, or alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the output format (compact markdown, soul, preference facts, episodic tail), conditions for empty/minimal results, its appearance in other calls, and its exclusion of full recall/skills. It also discloses namespace filtering behavior. This is exemplary transparency.

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

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

The description is front-loaded with the primary purpose, then delivers compact, high-value details about content, edge cases, and cross-tool behavior. Every sentence contributes, and the prose is dense without being verbose. Structure and length are optimal 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?

Given the output schema exists (signal indicates yes), the description need not explain return structures. It covers what the profile contains, when it may be empty, how it relates to other calls, and the parameter's effect. No critical information for correct invocation is missing.

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

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

The schema already provides 100% coverage for the single 'namespace' parameter, including its meaning and failure behavior. The description adds a redundant phrase ('namespace= excludes...') but no new information beyond the schema. Per the baseline rule, when schema coverage is high, a 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 action ('Return a token-capped bootstrap profile') with a clear resource (the caller's memory profile). It also differentiates itself from siblings by explicitly noting it 'Does not dump full recall or the skills catalog', which distinguishes it from memory_recall and memory_tools_catalog. The purpose is unambiguous and actionable.

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 provides context on when the tool is used ('Also returned on memory_session_ensure... prepended on agent_run_start'), which implies it's for bootstrapping sessions. It also hints at alternatives by stating what it does not do, but lacks explicit 'use this when' or 'use that instead' guidance. It's clear but not fully prescriptive about 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?

With no annotations provided, the description carries the full burden and does so thoroughly: default scope is durable pillars only, default recall is current truth with superseded rows omitted, namespace excludes rather than demotes, provenance is metadata-only (never page HTML), and deadline_seconds degrades per-pillar instead of killing the call. These are meaningful behaviors beyond the name.

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?

Front-loads the cheap two-step pattern before the parameter-specific guidance. It is dense and somewhat long, and the detail="summary" explanation partially repeats the schema, but for a 15-parameter tool most sentences still earn their 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?

An output schema exists, so return values need not be re-explained, and the description still flags that results include org/bound and per-hit provenance. Combined with the coverage of defaults, scoping, filtering, point-in-time recall, and timeout behavior, an agent has everything needed 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?

Schema description coverage is 100%, so the baseline is 3; the description adds cross-parameter workflow meaning (summary-first then get, when to set scope/agent/explain, short keyword anchors for entity queries) rather than merely restating fields. It stops short of adding full syntax detail, which the schema already provides.

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

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

States a specific verb+resource (hybrid recall across memory pillars) with explicit org scope. It also distinguishes itself from the sibling memory_get by describing the intended two-step flow, so an agent can tell the two apart without opening schemas.

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

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

Gives explicit when-to-use guidance: call with detail="summary" first, then memory_get for chosen hits; scope=["working"] to include session turns; agent= to narrow semantic/episodic; short keyword anchor for entity questions; explain=true to prefer matched_keyword hits. It names the alternative (memory_get) and the conditions that select each 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?

With no annotations, the description carries the full burden and does well: it discloses the guarded ingestion pipeline (PII, injection screening, near-dupe merge, contradiction supersede), RLS enforcement, namespace allowlisting with first-write creation, and that the result contains `org` + `bound`. It omits permissions/auth requirements and any irreversibility or rate-limit notes, which keeps it below 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?

The purpose sentence is front-loaded and the kind-routing rule follows immediately, with the heavier behavioral detail later. It is dense but every clause carries information; the pipeline and RLS sentence could be tightened slightly, preventing 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 9-parameter write tool with an output schema present, the description covers everything the agent needs: kind routing, rejected kinds and their alternatives, tagging behavior, namespace semantics, and pipeline side effects. Return values need not be explained because an output schema exists.

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 every parameter is already documented in the schema, including repo->tag, github->tag, paths->tag, and namespace default resolution. The description largely restates this (repo/github tagging, namespace container, paths tags) rather than adding syntax or edge cases 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 opening line gives a specific verb+resource ('Write a durable memory into the caller's org') and the rest of the text maps each `kind` to a storage pillar while naming the sibling tools (memory_procedure_set / memory_skill_set) used for rejected kinds. An agent can tell this apart from memory_recall, memory_session_append, and the *_set siblings 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?

It explicitly routes kinds: fact/preference/note/outreach to the semantic pillar, event to episodic, and tells the caller to use memory_procedure_set / memory_skill_set instead of passing procedure/skill. It also explains when to pass repo/github versus omitting them ('Omit for cross-cutting memories'). It stops short of an explicit when-to-use-this-vs-memory_recall statement, so it is not a full 5.

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

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

With no annotations, the description must disclose behavior. It explicitly describes the self-healing mechanism: if session_id expired/closed, a fresh session opens and the response carries a new session_id and reopened:true. It also explains how repo/github/topic affect scope. This covers the main side effects, though it doesn't mention any potential data loss on the old session or auth/rate limits, which are not critical here.

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 primary action. The first sentence is the core purpose; the second expands on self-healing and parameter usage. No wasted words; 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?

An output schema exists, so return values are already covered. The description explains the self-healing behavior and parameter effects, which is sufficient for an agent to call this tool correctly. It doesn't define 'turn' explicitly, but role and content parameters make it clear. The description is complete for practical use.

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?

All 6 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds meaningful context beyond the schema: it explains that repo 'preserves workspace scope and updates the state pointer', and that topic/github are 'used when reopening after expiry'. This extra context helps the agent understand the parameters' purpose, raising the score.

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+resource: 'Append a turn to a working-memory session'. This clearly states the tool's action and distinguishes it from sibling tools like memory_session_open (which opens a new session) or memory_session_close (which closes one). The 'self-healing' hint further clarifies its niche.

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 explains when to use this tool implicitly by describing the self-healing behavior for expired/closed sessions and how to preserve scope via repo/github/topic. It also mentions avoiding a manual memory_state_set, which hints at an alternative. However, it doesn't explicitly compare with memory_session_open or state when NOT to use this tool, though the core usage 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?

With no annotations, the description carries the behavioral disclosure burden. It reveals an important side effect: if distill defaults to true, the transcript is queued for a background worker to create durable org-scoped memories. It does not cover session finality, reversibility, or failure behavior, but the key side effect is transparently disclosed.

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 filler: the first states the core action, the second explains the optional distill behavior. It is front-loaded and every clause earns its place.

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

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

For a low-complexity tool with full schema coverage and an output schema, this description is complete. It covers the required input, the optional flag, and the important side effect, so an agent can invoke the tool correctly without needing additional 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%, so the baseline is 3. The description adds meaningful detail for the distill parameter, explaining the background worker and durable org-scoped memory outcome beyond the schema's 'semantic/episodic memory' phrasing, and it clarifies the default behavior. session_id is adequately documented by the schema itself.

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

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

The first sentence states a specific action and object: 'Close a working-memory session.' This clearly identifies what the tool does and contrasts with sibling tools like memory_session_open and memory_session_append through the verb '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 does not explicitly say when to use this tool versus alternatives such as memory_session_open or memory_session_append. The only conditional guidance is about the distill flag, not about choosing this tool, so usage is implied rather than stated.

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