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, the description must carry the behavioural load, and it does disclose the admin requirement, the seat refusal, and the meaningful "0" blocks every new run semantics for the spend cap. It is silent on mutation-relevant behaviour such as duplicate-slug handling, idempotency, and what side effects creating a record triggers, which matters for a write tool with zero 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?

Two tightly packed sentences that lead with the action and resource, then the capability surface, then the gating rule; nothing is padding. The issue-tracker references (#733/#734) are the only noise, and they are minor.

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 15-parameter creation tool whose schema is fully documented and which has an output schema, the description covers purpose, the configurable surface, and the permission/seat gate — enough for an agent to decide and call correctly. Remaining gaps (duplicate-slug behaviour, what is auto-provisioned) are refinements rather than blockers.

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 every parameter, including enums and defaults, so the baseline is 3. The description's summary of configurable aspects (model, tools, standing procedure, memory lens, focus, spend cap) largely restates what the schema fields already say and adds no syntax or constraint detail of its own.

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 ("Create a dedicated agent record") and enumerates the configurable surface (model, tools, standing procedure, memory lens, focus, spend cap), so an agent knows exactly what is produced. It does not explicitly differentiate itself from the neighbouring agent_update or agent_get, so sibling routing is left to inference from the verb '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?

"Needs org:admin; agent seats are refused" gives a real precondition and a refusal condition, which is more than most definitions offer. However, no alternative is named — it never says to use agent_update to change an existing agent or agent_get to inspect one — so the when-to-use decision against siblings is only implied.

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 null semantics for the budget block and the exact degraded behavior on spend-lookup failure (keeps saved period and budget_usd, sets error to unavailable). It does not mention permissions/auth needs, but the read-only nature is evident from "Read".

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, then the budget-block edge case, then the sibling routing. Every clause earns its place, though the budget-block sentence is dense and the charter sentence is slightly tangential.

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 needn't be explained, yet the description usefully previews the budget block and its failure mode, and points to the tool holding the charter. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% for the single slug parameter, and the description adds no syntax or format detail beyond what the schema already documents. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ("Read one agent record") and enumerates the contents (kind, status, model pin, tool patterns, budget block). It is clearly distinguishable from agent_list (multiple), agent_create/update (write) and from memory_agent_get, which it names as the holder of the charter.

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 word "one" and the slug-bound schema make the single-record fetch context clear, and the closing sentence routes the agent to memory_agent_get for the charter, an explicit alternative. There is no explicit when-not guidance versus agent_list, so it falls short of a 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the sort order and the conditional 'budget block when that agent has a spend cap', but says nothing about pagination behavior, auth/permission requirements, or that this is a read-only operation beyond the verb 'List'.

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

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

Two tight sentences with the core action front-loaded and zero filler. The parenthetical '(the manager leads)' is slightly cryptic but earns its place by explaining the ordering semantics.

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 needn't be described, and 75% of params are schema-documented. The description usefully adds the ordering and conditional budget-block behavior; the main gap is that a no-annotation read/list tool leaves pagination and safety characteristics implicit.

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

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

Schema description coverage is 75% (kind, cursor, status documented; limit bare), and the description adds no parameter-level meaning of its own. It only describes row content, so the schema does essentially all the work — a 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?

States a specific verb+resource ('List this org's agent records') and adds the ordering rule (oldest first, manager leads), so an agent knows exactly what the operation returns. It does not explicitly distinguish itself from siblings like agent_get or agent_routine_list, but the verb+resource pair is 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as agent_get for a single record. The only usage-adjacent signal ('archived records are listed only when asked') lives in the schema's status param, not the description.

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. "List" implies a read-only operation and it names returned fields, but it omits pagination behavior, permissions, rate limits, and error handling.

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 filler; every phrase identifies the operation, scope, or returned data.

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 list tool with an output schema, the description covers purpose, scope, and key fields. It remains incomplete on pagination semantics and usage guidance, but the output schema reduces the need to explain return values.

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

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

Schema coverage is 67%, and the description's "one agent" reinforces the required agent_slug parameter. It adds no detail about limit or cursor, but the schema already documents two of the three parameters.

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

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

The description states a specific verb ("List") and resource ("routines") with a clear scope ("on one agent") and lists the key fields returned. It is clear, though it does not explicitly distinguish itself from the sibling mutation tool agent_routine_set.

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

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

There is no explicit when-to-use guidance, no exclusions, and no alternatives named. The usage is only implied by the tool name and the phrase "on one 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 does well: each fire starts an unattended run bound to the agent, the run executes on the setting person's authority, and the outcome posts into that person's channel with the agent. The seat/admin gating and refusal of specialist seats are disclosed. It omits what an update does to pre-existing routine fields and whether runs are billable or throttled.

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 compact sentences, front-loaded with the create/update purpose before the behavioral and permission detail. The parenthetical issue reference '(#736)' is opaque noise that does not help an agent decide anything.

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 no explanation, and the description covers purpose, side effects, authority model, and permission gating. It leaves open how updates merge with existing routines and how this relates to the sibling list/cancel tools, which keeps it short of 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%, and the schema already documents cron format, timezone, enabled, name handle, agent_slug, and prompt. The description adds no parameter-level meaning beyond what the schema provides, 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?

States a specific verb pair (create or update), a specific resource (standing cron routine), and its target (an agent), which cleanly distinguishes it from sibling agent_routine_list. An agent can tell what this does 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 strong operating context: it is for standing/scheduled routines, requires org:admin acting as a person, and specialist seats are refused. It does not explicitly name alternatives (e.g. agent_run_start for one-off runs) or state when an update path is preferred over delete/recreate, so it falls short of 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 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 usefully discloses that only summary and artifact refs are returned and that the child transcript is not appended to this run's history. However, it omits operational behavior such as credit consumption, failure handling, concurrency limits, and whether the call is blocking beyond the phrase 'to completion'.

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 short sentences and front-loads the core action. Every sentence adds relevant information: the operation, the restricted availability, and the transcript isolation behavior.

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

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

The output schema exists, so return values need not be explained in detail, and the input schema covers parameters richly. The description supplies the key non-obvious context about nested execution and transcript isolation, though it leaves out some operational details like credit impact and failure modes.

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 input schema already documents all seven parameters thoroughly. The description adds no parameter-specific meaning beyond what the schema provides, which is the baseline expectation when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: run a nested Cloud Agent to completion. It explicitly distinguishes this from top-level run tools by saying it is only available inside an active TeamShared Cloud Agent run and returns only summary and artifact refs.

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 a clear precondition, that it only works inside an active TeamShared Cloud Agent run, but it does not contrast this with alternatives such as agent_run_start or agent_run_followup. The usage is implied rather than explicitly 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, the description carries the full burden and does so richly: model substitution is reported as model_substitution, tool narrowing is inherited and further restricted to the calling run's allowlist with tools_not_permitted, child-kind callers drop shell/browser/secret HTTP, no-calling-run keeps target tools, and budget exhaustion refuses with agent_budget_exceeded while leaving the running turn alone. That is exactly the pre-call 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 one-line purpose, then trades detail for correctness; every clause about substitution, allowlists and budget maps to a real decision point. Sentences are long and jargon-dense (e.g. 'Keeps the run's tools narrowing and agent record'), costing a little readability.

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

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

For a complex nested-run tool with no annotations, the description covers the behaviors that matter (model re-check, tool inheritance/allowlist, budget refusal, running turn preserved), and return values are covered by the existing output schema, so nothing essential is missing.

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

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

Schema description coverage is 100% and the schema already explains prompt, run_id (TeamShared UUID or Cursor run-… id), cursor_agent_id (used when run_id is omitted) and the agent label. The description references 'a run bound to an agent' but does not clarify precedence or when to prefer cursor_agent_id over run_id, so it adds little beyond the schema — baseline 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?

The first sentence names a specific verb and resource — 'Enqueue a follow-up prompt on an existing TeamShared Cloud Agent' — and the word 'existing' separates it from agent_run_start (creating a new run). An agent can pick between the two siblings 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 'existing ... agent' framing plus repeated contrasts to agent_run_start and 'a nested start' make the when-to-use context clear. It never states the negative case outright (e.g. 'to create a new run use agent_run_start instead'), so it stops short of full routing guidance.

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

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

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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses one-active-run-per-work-item concurrency, budget refusal semantics (agent_budget_exceeded, nothing queued), allowlist narrowing that can never widen, nesting depth limits, model substitution, auto PR defaults, and durable_memory's ephemeral-by-default behavior. These are exactly the mutation side effects an agent needs before calling.

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 carries information and the purpose is front-loaded, but the body is a dense, unbulleted blob with mid-sentence line breaks that make it hard to scan. The volume is defensible for a 13-parameter tool, yet the lack of structure costs it.

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 13-parameter mutation tool with no annotations, the description covers concurrency, permissions, failure modes, and injection behavior well, and an output schema exists so return values need not be explained. The remaining gap is sibling disambiguation against agent_run_child and agent_run_followup, which matters because nesting is a described behavior of this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new semantics: explicit model= beats the agent record's model, explicit tools= can only narrow the agent's, github defaults depend on the work item's code tag, and durable_memory changes nested-run lifecycle. It goes past restating the schema, though playbook_slug is referenced in prose despite not being a parameter of this tool.

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

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

The opening sentence states a specific verb and resource ("Start a TeamShared Cloud Agent (router + FastMCP)") and rules out a plausible misreading with "Not a Cursor VM." It does not, however, differentiate itself from close siblings like agent_run_child or agent_run_followup, so an agent still has to infer which run-starting tool applies.

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

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

Usage conditions are implied rather than stated as routing rules: busy runs return status=busy, budget-capped agents are refused, nested starts are capped at a fixed depth. There is no explicit "use this instead of agent_run_child/agent_run_followup when..." guidance, so the when-to-use decision against siblings remains inferential.

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 disclosure burden. It usefully reveals that traces are *stored* and only available for terminal runs, implying non-terminal runs yield nothing — genuine behavioral context. It says nothing about permissions, whether traces expire, or that include_io materially changes payload size, which is a real gap for an unannotated read 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?

One sentence, front-loaded with the verb and resource, with the terminal-run constraint appended. Nothing redundant or 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?

An output schema exists, so return values need not be described, and both parameters are fully covered by the schema. The remaining gap is routing guidance against the many agent_run_* siblings and clarity on which terminal states have persisted traces.

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 fully documents run_id and include_io including default and size limits. The description adds no parameter meaning beyond that, so 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?

States a specific verb (Return) and a specific resource (the stored model/tool/error trace tree), which is clearly distinct from sibling readers like agent_run_status or agent_run_list. It does not explicitly name a sibling alternative, but the resource is specific enough that an agent can tell what it retrieves.

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?

"for a terminal run" gives an implied precondition — the run must be finished — which is meaningful selection guidance. However, it never states what to use for a live/in-progress run (agent_run_status) or whether cancelled/failed runs qualify as terminal, so alternatives are left 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, the description carries the full burden and does disclose the authorization requirement, two hard refusal cases, and the manager-record exception. It does not say whether unspecified fields are preserved or that list-valued fields are wholesale replacements, but those semantics are stated in the schema rather than contradicted 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, zero filler: the first front-loads what changes, the second front-loads the constraints that decide whether the call is even legal. Nothing is repeated from the schema.

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

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

An output schema exists, so return values need no explanation, and the schema covers all 17 params in detail. The description adds the operational gate (org:admin, seat/manager refusals) that an agent cannot infer from the schema; the only gap is that replace-vs-merge semantics live solely 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 description coverage is 100% across 17 parameters, so the schema already explains clearing behavior ('[] clears', 'empty string clears'), the budget/clear_budget interaction, and the MCP/GitHub grant shapes. The description only restates the field families in prose ('tools, status, standing procedure, lens, focus or spend cap') without adding format or interaction detail, so baseline 3 applies.

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

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

States a specific verb ('Change') plus the resource ('an agent record') and enumerates the mutable surfaces (tools, status, standing procedure, lens, focus, spend cap). It is clearly distinguishable from agent_create/agent_get/agent_list by the mutation verb, though no sibling is named explicitly.

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

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

Gives real preconditions and exclusions: 'Needs org:admin; agent seats are refused, and the manager's record is fixed (no cap on the manager).' That tells the agent when the call will fail, but it does not route between this tool and alternatives such as agent_create or the memory_* / agent_routine_set tools that also touch agent configuration.

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, 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 carries the full behavioral burden, and it only states what is fetched and by what key. It doesn't say whether the underlying ref can expire, what happens on an invalid/unknown ref, whether access is scoped, or that the operation is non-mutating beyond the implication of 'Retrieve'.

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 action and the key input are both in the first clause. It is efficient, though so terse that it leaves behavioral gaps that other dimensions must penalize.

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 one required parameter is identified. What is missing is error/expiry behavior and any tie-in to the compression tool that generates the refs, leaving the agent to infer failure modes.

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 single parameter 'ref' is already documented in the schema as 'CCR ref from a compressed message (ref=ccr_...)'. The description's 'via CCR ref' adds no format, sourcing, or validity detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (the original content for a compressed block) plus the mechanism (via CCR ref), so an agent can separate it from context_compress, context_prepare and context_normalize. It does not explicitly name a sibling, which keeps it 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 use case is implied by the phrase 'for a compressed block' - you come here when you hold a ref produced by compression. There is no explicit when-to-use statement, no named alternative, and no exclusions (e.g. what to do if the ref is stale or expired).

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 burden and does disclose a non-obvious trait: a free org's monthly allowance is granted on this read, once per UTC month — a side effect an agent would otherwise not expect from a 'balance' call. It does not state auth requirements or whether reads are rate limited, leaving a modest 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?

Front-loaded with the core action in the first sentence, then units, then the free-org caveat, then the exclusion. Every sentence answers a distinct question an agent would ask; nothing is padded.

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

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

With an output schema present, the description needn't describe return values, and it covers the two things the schema cannot: unit scaling and the monthly allowance side effect. Without annotations, a note on permissions or read safety would round it out, but the essentials are there.

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 takes zero parameters, which is the baseline-4 case. The description's unit explanation (1 USD = 1,000,000 micro-USD) actually pertains to the response rather than inputs, but it is still the kind of semantics an agent needs to interpret results correctly.

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

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

States a specific verb and resource: 'Return the current org's prepaid router credit balance.' No sibling tool covers billing or credits, so an agent can distinguish this immediately; the scope ('current org', 'prepaid router credits') is 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?

Explicitly rules out an adjacent intent: 'Credit packs are purchased on the billing page, not through this tool,' which prevents the agent from hunting for a purchase tool here. It lacks a positive statement of when to reach for this versus account_brief, so it stops short of full when/when-not coverage.

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, the description carries the burden alone. 'History is never mutated' is a genuinely useful disclosure of the append-only, non-destructive semantics that an agent could not infer elsewhere. It omits permissions, whether the stream must pre-exist, and the fact that several event-type prefixes are rejected server-side (only in 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?

Two short sentences, neither wasted: the first states the action, the second states the invariant. Purpose is front-loaded and there is no filler.

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

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

An output schema exists and the schema fully documents all 7 parameters, so the description needn't cover return values or field syntax. What remains missing for a 7-param write tool with zero annotations is routing guidance versus event_list and any precondition or failure-mode note.

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 (stream_id formats, event type naming rules, actor ignored, payload corrections) is documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (append) and resource (one event to a stream), which immediately distinguishes it from the read-side sibling event_list. It stops short of explicitly naming that sibling or the adjacent write tools, so differentiation is implied rather than stated.

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 when-to-use guidance: nothing says to prefer event_list for reading, nor what preconditions exist (must the stream already exist? are there event-type restrictions?). The immutability note hints at a correction workflow (append rather than modify) but only in the schema's payload text, not the description.

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 disclosure burden and does well: it declares the write is an append-only event, names the source-of-truth record ('evidence.attached' on 'run:{id}'), and states the supersede behavior of a second attach to the same slot. It omits auth/permission requirements and any failure modes, keeping it below a 5.

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

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

Three compact sentences, front-loaded with the action and followed by mechanics and routing advice; each sentence carries distinct information. Minor density from internal terms like 'evidence.attached' and 'run:{id}', but nothing is redundant.

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 mutation tool with an output schema and no annotations, the description covers the essential mechanics (append-only, source of truth, supersede, preferred alternative). What remains missing is permission/authorization context and error behavior, which leaves a small but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema by explaining that a second attach to the same slot supersedes the prior pointer, which clarifies the interplay of 'slot' and 'supersedes'. It does not elaborate on 'kind' inference or 'pointer' formats 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 first sentence states a specific verb and resource ('Attach evidence to a Process run') plus the mechanism ('via an append-only event'), which distinguishes it from evidence_get, evidence_require, file_create, and storage_attach. An agent can tell what it does 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 explicitly names preferred alternatives ('prefer this (or file_create(work_id=) auto-attach) over mutating a case-file row'), giving real routing guidance against a named anti-pattern. It stops short of saying when to call evidence_require or evidence_get instead, so no explicit exclusions are 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?

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 supplied, the description carries the full burden, and it does disclose two real behaviors: the write is append-only, and declared slots are reconciled against received attachments into missing / received / superseded states. It still omits whether the run must be in a particular state, whether declaring a duplicate slot errors or supersedes, and any permission requirements for a mutation 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?

Two sentences, front-loaded with the core action and no filler. The second fragment is compressed to the point of being slightly cryptic ('Folded with received attachments'), but it still earns its place by explaining the resulting state model.

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 and the input schema is fully annotated, so return values and field meanings need not be restated. What remains missing is the tool's position in the evidence workflow relative to evidence_attach and evidence_get, which matters for a tool that only makes sense as one half of a requirement/fulfilment pair.

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 including kind, slot, step, agent, title and run_id is already documented in the schema, which sets the baseline at 3. The description adds no format or semantics beyond that, though its 'folded with received attachments' line does clarify how the slot value is later matched.

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: 'Declare required evidence on a Process run', which distinguishes it from the sibling evidence_attach (which supplies evidence rather than declaring a requirement). It stops short of naming that sibling explicitly, so the agent must infer the pairing from the name alone.

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

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

Usage is implied by 'Declare required evidence on a Process run', and '(append-only event)' hints this is a declaration step in a run lifecycle. There is no explicit when-to-use/when-not guidance, no mention of prerequisites such as the run being open, and no named alternative to evidence_attach or evidence_get.

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 that files are retained with full version history for audit, that the bucket mirror is cleaned up only if published, and that the public /s/{share_token} route returns 404. It stops short of stating reversibility/restore path or permission 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?

Two tight sentences with zero filler; the primary action and its immediate scoping effect are front-loaded, and the follow-on retention/404 details come second.

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 important side effects of a mutation. It omits whether the archive is reversible or what a restore would require, which is the one meaningful gap for a destructive-adjacent operation with no annotations.

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% for the single file_id parameter, so the schema already carries the semantics. The description adds no syntax or format detail beyond what the schema provides, making the baseline 3 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?

States a specific verb (archive) applied to a specific resource (a shared file), and details the scope: exclusion from active lists plus bucket-mirror cleanup. This clearly distinguishes it from siblings like file_unpublish or file_version_delete 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 description implies when archive is appropriate by describing its effects, but never explicitly contrasts it with the closest alternatives (file_unpublish, file_version_delete) or states when not to use it. Usage is inferable rather than 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?

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 substantial work: it discloses the resulting visibility state, that the share token is retained for audit, that the public route returns 404, and that bucket cleanup is best-effort rather than guaranteed. The main omissions are authorization requirements and behavior when the file was never published (error vs. no-op).

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 primary effect is front-loaded and the behavioral caveats follow. No filler or restated schema content.

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

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

For a one-parameter mutation with an output schema covering return values, the description supplies effect, side effects, and reversibility context (token retained). It stops short of stating permission requirements or the already-private case, which an agent could plausibly need.

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 a single self-documented param ('File UUID to unpublish'), so the schema already carries the parameter meaning. The description adds nothing about the identifier's format or provenance, which is expected at this coverage level.

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 (revoke public access to a shared file) and clarifies the resulting state ('visibility back to private'), so the agent knows exactly what changes. It does not, however, distinguish itself from the near-identical sibling storage_unpublish or reference its inverse file_publish, so sibling differentiation is left to inference.

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

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

Usage is implied by the effect described (call it when a file should stop being public), but there is no explicit when-to-use framing, no prerequisites (e.g. ownership/permission requirements), and no routing hint against the closely named sibling storage_unpublish. Adequate but with clear gaps.

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 the full behavioral burden and does it well: single-use token, ~10 minute expiry, returned artifacts (upload_url, upload_token, expires_in_seconds, self-deleting script), exact invocation pattern, and that the script prints the file id. Update mode is further qualified with what is preserved (title/slug/share_token) and that the bucket mirror is re-published when already published.

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 purpose in sentence one, then a scoping paragraph, then the return/invocation flow, then a bolded section for update mode — a clean progression. A few clauses (e.g. restating the script's delete-on-success behavior alongside the TTL) are slightly redundant, but nothing is padding.

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

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

For a 9-parameter tool with no annotations, the description supplies the operational contract an agent actually needs: what to do with the returned script, how the token is consumed, what happens on update versus create, and how publishing interacts with versioning. An output schema exists, yet the description still front-loads the key return fields so the agent knows what to expect before calling.

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 semantics on top: it clarifies that title is ignored in update mode, that file_id switches the whole tool into version-append mode, and that publish=true yields a public URL in the script output. It does not explain content_format options (diagram/sheet) or the work_id/project_id attachment semantics, which remain schema-only.

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 and resource ('Get a one-time uploader script to push a local file into a shared file') and the following lines immediately scope it against siblings: inline content goes to file_create/file_update, binaries go to storage_upload_request. An agent can place this tool precisely in the file-handling family 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?

Explicit when-to-use is given ('For large local HTML/Markdown files that don't fit inline'), plus two named alternatives for the cases this tool does not cover. It also documents update mode ('pass file_id to append... This is the supported way to push a new version of a large file'), so both create and update scenarios are routed correctly.

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

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

With no annotations, the description carries the full burden and does so well: it declares destructiveness/irreversibility, the guard against deleting the last version, the side effect of bumping current_version, and the conditional bucket re-publish that keeps the public /s/{slug} route consistent. This is exactly the hidden-state disclosure an agent needs before a mutation.

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 destructive warning and single-version scope are front-loaded, which is the right ordering for a dangerous operation. The sentence about bucket re-publishing is dense but relevant; only minor verbosity from restating return fields that the output schema already defines.

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?

Return fields are redundantly listed even though an output schema exists, and no sibling alternative is mentioned. Otherwise the safety profile and cascading side effects are thoroughly covered for a destructive two-parameter mutation.

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 file_id and version both documented in the schema, so the schema already does the heavy lifting. The description adds no format, range, or lookup guidance beyond what the schema provides, 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 precise verb and narrowly scoped resource: deleting a single version of a shared file, as opposed to removing the file itself. The '(destructive, irreversible)' tag immediately sets it apart from read-oriented siblings like file_get and file_list.

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

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

It communicates an important applicability constraint (refuses to delete the only remaining version), which tells the agent when the call will not work. However, it never names an alternative such as file_archive or file_unpublish, so the agent must infer when whole-file removal is preferable to version removal.

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 and does useful work: it discloses the required agent-writes switch and that closing is treated as a destructive action subject to review approval by default. It does not say whether closing is reversible or whether reopening is possible, but the gating and approval behavior 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?

The description is front-loaded with the core action and then states the two key operational constraints. Every sentence earns its place and there is no wasted text.

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, all parameters are documented, and an output schema exists, so return-value explanation is unnecessary. The description also covers authorization and approval gating, though it could say more about reversibility or the practical effect of closing.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description does not add syntax or meaning beyond the schema, which is acceptable at the baseline 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: closing an issue or pull request. It is clear and distinguishable in general, but it does not explicitly differentiate itself from nearby siblings such as github_merge or github_delete.

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

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

It states prerequisites — the org's agent-writes switch and review settings — but gives no guidance on when to use this tool versus alternatives. There is no mention of when not to close, or how this relates to github_merge, github_delete, or work_close.

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 full burden. It does add real value with an auth requirement ('Requires memory:read') and an error-behavior pointer ('Same binding errors as github_repo_get'), but that cross-reference is opaque without already knowing the sibling, and it never states read-only semantics or result limits.

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

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

Two short sentences with the scope statement front-loaded and zero padding. The only weak spot is the cryptic 'Same binding errors as github_repo_get' line, which is compact but costs the reader a lookup.

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 needn't be described, and both params are fully documented. However, for a code-search tool the description says nothing about result caps, pagination, or which branches/refs are searched — meaningful gaps for invocation correctness.

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

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

Schema coverage is 100% and the schema already explains both parameters, including the fact that repo:/org: qualifiers are ignored. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb + resource + scope: 'Search code in one connected repo.' That clearly separates it from github_file_get (single file), github_tree (structure listing), and object_search (non-code objects). It stops short of naming a sibling alternative, so it's clear but not fully differentiated.

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

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

'in one connected repo' implies the usage boundary (single-repo, not cross-org), and 'Requires memory:read' gives a prerequisite. But there is no explicit when-to-use versus github_tree/github_file_get for locating code, and no statement of when this tool is the wrong choice.

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 disclosure burden. It usefully states the agent-writes prerequisite, but does not describe side effects, failure modes, rate limits, or whether comments are editable/deletable; return details are partly handled by the output 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?

Two short sentences, front-loaded with the action and followed by the key prerequisite. There is no redundant or filler text.

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 comment-creation tool with full parameter documentation and an output schema, the description provides adequate scope and the important permission prerequisite. It could be stronger by stating how it relates to sibling commenting tools, 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 three parameters, including that github can be omitted to use the run-bound repository. The description reinforces the run-repository default but adds no additional 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 states a specific verb and resource: commenting on an issue or pull request in the run's repository. This is precise enough that an agent can distinguish it from issue/PR reading or work-item commenting tools.

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

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

It gives a clear usage context and a prerequisite: the org's agent-writes switch must be enabled, and the action targets the run's repository. It does not explicitly name alternatives such as work_comment_add or explain 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, the description carries the full load and does well: it discloses the write-authorization prerequisite, the approval gate, and a hard guardrail (bound repo undeletable). It stops short of saying whether deletion is reversible or how a missing branch is handled, which is the remaining gap for a destructive mutation.

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-loaded with the action, then constraints. Every sentence adds distinct information (verb, auth switch, review gating, repo guardrail) with zero 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?

An output schema exists so return values need no explanation, and the schema fully documents parameters. The description supplies the authorization and safety context an agent needs before calling a destructive tool; only reversibility/error behavior is left unstated.

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% – each of name, github, and target is documented in the schema itself, including the target enum. The description adds no parameter-level detail beyond what structured data already provides, so it sits at the baseline.

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

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

States a specific verb and resource ('Delete a branch or a ref') and bounds the scope by declaring the bound repository cannot be deleted. An agent can immediately tell this apart from siblings like github_push, github_merge, or github_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?

Explicitly names the precondition ('Requires the org's agent-writes switch') and warns that deletion is gated by org review settings with human approval by default, which tells the agent when this tool will actually execute. It does not name alternative tools for branch cleanup, but no close sibling offers that.

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 disclose real behavior: large files truncate and signal truncated=true, and the call requires memory:read. Remaining gaps are minor (error shape on a missing path or bad ref), and the truncation flag is a genuinely useful caveat an agent would otherwise miss.

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

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

Three short sentences, front-loaded with the core action, then the truncation caveat, then the auth prerequisite. Nothing is redundant and nothing needs trimming.

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-shape explanation isn't required, and the description still volunteers the one return detail that matters (truncated=true) plus the permission requirement. For a three-parameter read tool this is close to complete; only failure modes for bad refs/paths are unaddressed.

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% — ref, path, and github are each documented in the schema with defaults and constraints. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

"Read one file from a connected repo" gives a specific verb and resource, and the singular-file scope implicitly separates it from github_tree, github_repo_get, and github_code_search. It stops short of naming those siblings explicitly, so the differentiation is inferred rather than stated.

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 this tool applies (you have a known path and want its contents) but never states when to prefer github_tree, github_code_search, or github_repo_get instead. The only cross-reference, "Same binding errors as github_repo_get," is about error behavior, not tool selection.

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

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

With no annotations, the description carries the burden and does meaningful work: it discloses that the body is only an excerpt (a real behavioral caveat an agent would otherwise miss), states the memory:read scope requirement, and points to github_repo_get for the binding-error class. It is silent on read-only semantics, rate limits, and pagination, 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?

Three short sentences, front-loaded with the action and the most important caveat (body is an excerpt). The cross-reference to github_repo_get is compact rather than wasteful, though it is opaque without reading that tool.

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. For a two-parameter read tool, the description covers the action, the content-truncation caveat, the required scope, and where binding failures are documented — everything an agent needs 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 both parameters are already documented in the schema. The description's 'connected repo' phrasing loosely reinforces the meaning of the github parameter, but adds no format detail 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?

Specific verb and resource: 'Fetch one issue from a connected repo.' The singular 'one issue' implicitly separates it from github_issue_list, but the description never names that sibling, so differentiation is inferred rather than stated.

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

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

Usage is only implied: you call this when you have a specific issue number. There is no explicit 'use X instead when...' guidance against github_issue_list, github_pr_get, or work_get, and no stated prerequisites beyond the auth note.

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 present, the description carries the full disclosure burden; it does state the auth scope (memory:read), that the operation is a read, that PRs are filtered out of results, and that binding failures mirror github_repo_get. It omits pagination/limit behavior, ordering, and whether results are capped, which matter for a list 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?

Three short sentences with the core purpose front-loaded and no filler. The final sentence relies on cross-referencing another tool's behavior, which is compact but assumes the agent knows github_repo_get's failure modes.

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 documentation is not needed, and auth plus error behavior are covered. However, for a list endpoint the description leaves open pagination/filtering semantics and alternative-tool routing, leaving gaps an agent would need to probe.

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%, including the state parameter's accepted values and default, so the schema already does the parameter work. The description adds nothing beyond confirming the repo must be one "the org's GitHub App serves," which the schema also conveys — 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 ("List issues") with a scoping qualifier ("in a connected repo") and an explicit content exclusion ("Pull requests are omitted"), which effectively separates it from github_pr_list. It stops short of naming github_issue_get as the single-item alternative, so the sibling differentiation is implicit rather than explicit.

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

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

The description gives a prerequisite ("Requires memory:read") and an error pointer ("Same binding errors as github_repo_get"), which are context, not usage routing. It never says when to reach for this vs github_issue_get or github_pr_list, so the agent must infer the choice from the resource 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. It usefully discloses that the org's agent-writes switch is required and that merging is treated as a destructive action subject to review, with a person's approval by default. It does not describe merge method behavior, branch cleanup, irreversibility, or what the response contains, so meaningful behavioral gaps remain.

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, front-loaded with the action, and then moves immediately to the prerequisite and approval constraints. Every sentence earns its place and there is no redundant restatement of the schema.

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

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

An output schema exists, so return values do not need to be explained. The input schema fully documents both parameters, and the description adds the key authorization and approval context for a mutation tool. It is reasonably complete for calling the tool, though merge-specific behavioral details are absent.

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 fully documented in the input schema. The description adds no parameter-level meaning beyond the schema and does not mention the PR number or repository binding context. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description uses a specific verb and resource: 'Merge a pull request.' This is clearly distinct from siblings like github_close, github_open_pr, or review_decide. However, it does not explicitly name any sibling or explain how it differs from adjacent operations such as closing or approving a PR.

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 prerequisite context: the org's agent-writes switch must be enabled, and approval follows the org's review settings for destructive actions. It does not explicitly say when not to use this tool or name alternatives, but the operational context is strong enough for an agent to know this is a gated merge action.

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 the behavioral load. It usefully discloses the authorization gate (agent-writes switch), that the operation is non-merging, and that the target repo is the run binding — genuine value beyond the schema. It says nothing about failure modes, e.g. what happens if the head branch was never pushed or a PR already exists for that head/base pair.

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, no filler, with the action stated first and the authorization constraint immediately after. Nothing repeats the schema or the name.

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 no explanation, and all parameters are covered in the schema. The description supplies the two things structured fields cannot: the write-authorization gate and the implicit repository binding. Sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema; baseline is 3. The description adds only one piece of meaning beyond that — that omitting `github` resolves to the run's bound repo — and says nothing about head/base relationships.

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 ('Open a pull request') scoped to 'this run's repository', and immediately clarifies it does not merge, which separates it from the github_merge sibling. An agent can tell what it does 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?

Names a concrete prerequisite ('Requires the org's agent-writes switch') and the non-merging scope, and explains the default repository binding ('The repository is the run's bound github='). It stops short of explicitly routing to github_merge for merging or to github_pr_get/github_pr_checks for follow-up, so alternatives are only implied.

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 burden itself and does disclose two real traits: an auth requirement (memory:read) and the degraded-result shape when the installation token can't read check runs. However it leans on 'Same binding errors as github_repo_get' as a cross-reference, and never states the read-only nature, rate limits, or whether statuses and conclusions are both returned.

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

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

Three short sentences, front-loaded with the core purpose and followed by the operational caveats. Minor cost is the cryptic 'Same binding errors as github_repo_get' clause, which is compact but opaque out of context.

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 isn't needed, and the auth/error context is useful. But for a tool whose error semantics are explicitly referenced via another tool's description, the definition leaves the agent to look elsewhere for that behavior.

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

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

Schema description coverage is 100%, so 'github' (owner/repo) and 'number' (PR number) are already fully documented. The description adds no format hints or constraints beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: check-run status for a single pull request's head commit. That is clearly distinct from github_pr_get (PR metadata) and github_pr_list, which an agent can infer without opening the schema. It stops short of naming a sibling alternative outright, keeping it at 4 rather than 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?

No guidance on when to call this versus github_pr_get or github_repo_get — the agent must guess that 'I need CI results for PR N' maps here. The only conditional language is a failure mode ('unavailable=forbidden when the installation token cannot read check runs'), which is availability information rather than usage direction.

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 disclose real behavior: file list and diff are capped, 'truncated=true' signals a cut, and a memory:read scope is required. It defers error semantics to github_repo_get for 'same binding errors', which is informative but not self-contained.

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

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

Three short sentences, front-loaded with the core action, then caveats (truncation) and prerequisites. No redundant text.

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-shape explanation is unnecessary, and the description covers truncation semantics and auth requirements. The only gap is that error behavior is only cross-referenced rather than described.

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