A portable context layer for MCP-speaking AI clients. Connect any client to one endpoint and it boots with your containers — structured context, live work state, and accumulated knowledge — carried across every client you use.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 35 tools
Most tools target clearly distinct resources, and the descriptions work hard to delineate boundaries (e.g. write_signal vs write_feedback vs patch_topology, and switch_deck vs load_deck vs switch_environment). A few clusters remain confusable — load_deck/read_deck/switch_deck/reground all concern entering or refreshing context, and write_knowledge/manage_knowledge split authoring from corpus maintenance, which is easy to misselect under time pressure.
The dominant pattern is verb_noun (create_deck, write_knowledge, patch_topology), but it is broken by bare verbs (commit, diff, reground) and by reversed noun_verb forms (connection_browse, connection_call, connection_list) and domain-prefixed names (team_work). Readable overall, but the mix of orderings and the inconsistent 'pcd_skill' infix show no single convention.
35 tools is heavy, but they spread across roughly ten coherent sub-domains (decks/containers, versioning, knowledge, skills, topology, signals, feedback, connections, meta, docs), averaging only a handful per area. It is defensible for a platform this broad, but the count is at the point where discovery and selection get costly.
Coverage is unusually broad: versioning (commit/diff/restore_version), full skill CRUD-ish lifecycle, knowledge find/read/write/manage, signal and feedback read/write flows, topology read/patch, and connection discovery/execution. The notable gap is deletion — no remove/delete tool for decks, skills, containers, or knowledge records — and lifecycle creation for some resources is implied rather than exposed.
Save a version snapshot of a supported object.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | No | Deck load handle as alternative to object_id. Resolved to deck_id server-side. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| object_id | No | UUID of the object (deck_id, console_doc id, container_id, or skill id). Required if handle not provided. | |
| skill_name | No | Skill name — for skill commits, resolves to skill id when combined with handle (deck that owns the skill). | |
| commit_note | Yes | Short description of what is in this version (not what will be in the next). Required — describes the snapshot's contents for the version chain. Empty strings rejected. | |
| object_type | Yes | Type of object to commit |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag mutating, non-destructive behavior, and the description is consistent, adding the 'snapshot' framing that implies append-to-version-chain rather than overwrite. The description aligns with annotations and adds that this is minimally useful layer, but does not disclose consequences such as whether versions become immutable, what happens on repeated commits, 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?
The description is a single 9-word sentence that front-loads the verb and uses no wasted words. The phrase 'supported object' is slightly under-specified, but the text earns its place by not tangentially referencing schema elements.
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 four object types, six parameters, and no output schema, the description is too thin: it neither explains what a successful commit returns (e.g., version identifier/confirmation) nor describes version-chain behavior or error cases. An agent can call the tool, but cannot anticipate the operational outcome.
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 fully documents all six parameters and the baseline is 3. The description adds no parameter-level semantics and does not even mention that object_type is restricted to the four enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource ('Save a version snapshot'), which conveys the core commit/checkpoint function and is distinct from siblings like restore_version or diff. However, it does not name the supported object types (deck, console_doc, container, skill) nor explicitly differentiate from any sibling, leaving 'supported object' vague until the schema is read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus restore_version, diff, or the create/update tools, and no exclusions or prerequisites are stated. The only operational hint (contract: true as a help mode) lives in the JSON schema rather than the description, so an agent choosing a tool gets no assistance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find external actions and retrieve their argument schemas before execution.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max actions to return (default 10). | |
| query | Yes | Natural-language description of what you want to do. E.g. 'create a linear issue', 'list notion pages', 'send a slack message'. | |
| toolkit | No | Optional toolkit filter: 'linear', 'notion', 'slack'. | |
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description uses non-destructive verbs ('find', 'retrieve') and aligns with the readOnlyHint and openWorldHint annotations. No contradiction exists between the description and the declared behavioral hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's function without unnecessary detail or repetition. It is well-structured for quick understanding.
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 effectively communicates what the tool does and what it returns (argument schemas), which is sufficient given the absence of an output schema. It allows an agent to understand the tool's role and expected output without extra context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover all parameters (query, limit, toolkit, contract) and the description matches their purpose, but it adds no extra semantic depth beyond the schema. Since schema coverage is 100%, 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 clearly states the tool's purpose: to find external actions and retrieve their argument schemas. It distinguishes itself from sibling tools like connection_call and connection_list by focusing on discovery and schema retrieval rather than execution or listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before execution' provides a clear timing and use case, but it does not explicitly compare with alternative tools or state when to prefer this over connection_call or connection_list. Still, the core usage guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute one or several independent external actions using discovered schemas. Returns a result for each call.
| Name | Required | Description | Default |
|---|---|---|---|
| calls | Yes | Up to 10 logically-independent calls. Order is preserved in the response. | |
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readonly and destructive potential, and the description adds that actions are independent and produce per-call results. However, it does not explain side effects, error behavior, or that calls may have lasting external impact beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, and each parameter has a concise, informative description. There is no redundant or extraneous 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?
With no output schema and only a one-line description, important context is missing regarding response format, error handling, and how discovered schemas are provided. The contract mode partially mitigates this, but the tool would benefit from more operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have clear schema descriptions: calls, action, args, and contract. The contract help-mode parameter is well explained, and the args object appropriately references the action's input schema. The dynamic nature of args limits deeper semantic detail, but the coverage is strong.
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 that the tool executes one or more independent external actions using discovered schemas and returns a result per call. It distinguishes this as a generic dispatching tool, though it could more explicitly contrast with the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus the sibling tools, nor any mention of prerequisites like needing discovered schemas or connection credentials. The phrase 'using discovered schemas' hints at context, but it does not provide concrete usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify services connected through PCD.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint and openWorldHint, but the description adds no further behavioral details. It does not explain the effect of the 'contract' parameter from the schema, nor does it mention any side effects or return behavior beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence without unnecessary words, but it is too vague to be fully effective. It earns its place in terms of brevity but lacks substantive clarification.
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 does not explain what the tool returns or how it behaves in typical usage. The schema parameter description hints at a contract mode, but the tool description itself leaves out critical context for an agent to understand the full operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single 'contract' parameter with a clear description, and the tool description adds no extra meaning. Since schema coverage is 100%, 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 'Identify services connected through PCD' gives a vague sense of listing or finding services but does not explicitly state that it returns a list of connections. It is somewhat distinguishable from sibling tools like connection_browse or connection_call, but the purpose could be clearer.
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 no guidance on when to use this tool versus alternatives such as connection_browse or connection_call. There is no mention of suitable scenarios or conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision a container through the prescribed setup workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining side effects. It does not mention what provisioning entails, whether it is reversible, or what the returned contract represents.
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 concise sentence with no filler. However, its brevity comes at the cost of substantive explanation, so it is only mildly effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with minimal annotations and no output schema, the description is too thin. It does not explain the setup workflow, the effect of contract mode, or any prerequisites, leaving agents with only the schema to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the only parameter, 'contract', is already well described in the schema as a help mode. The description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('provision') and resource ('container'), clearly indicating a creation operation. However, it does not differentiate from related sibling tools like resolve_container or write_container_meta.
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 such as resolve_container or create_deck. The phrase 'prescribed setup workflow' is too vague to convey the intended usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a deck from its applicable template.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name for the deck — unique per account. | |
| handle | Yes | Load handle — lowercase, hyphens, max 24 chars, unique per account. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| customise | No | Dot-path overrides applied to the template — e.g. { "deck.content.intent": "..." } | |
| deck_type | Yes | Deck type — closed 3-type set. Bootable: container-context, specialized-context. Passive: container-meta (the specialist roster). user-meta and company-meta are account configuration, not decks — use update_meta. | |
| container_id | No | Container ID to associate the deck with | |
| template_slug | No | Template slug — defaults to pcd-system-doc-schema-{deck_type}-json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds only the vague 'from its applicable template' and omits what actually happens on creation, whether a template is required or auto-selected, and any side effects. It adds little beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short sentence with no waste, but the terseness reflects under-specification rather than disciplined concision. It is appropriately front-loaded but too thin for a 7-parameter creation 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?
For a 7-parameter mutation tool with nested objects, an enum, and no output schema, the description is far too sparse. It says nothing about the required fields, the special 'contract' help mode, the deck_type set, or the template default, all of which the agent must discover from the schema alone.
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 fully documents name, handle, deck_type, contract, customise, container_id, and template_slug. The description adds no parameter meaning beyond the schema, 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?
The description states a specific verb and resource (create a deck) and adds that it derives from a template, which is more than a bare restatement of the name. However, 'its applicable template' is circular and it does nothing to distinguish this tool from siblings like create_container or create_pcd_skill. Adequate but with clear gaps.
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 is given on when to create a deck versus using load_deck, switch_deck, or update_deck, nor are prerequisites (e.g. needing a container) mentioned. The agent is left to infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a reusable working method when the user wants a procedure preserved for future use. Use update_pcd_skill to revise an existing method.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Skill name — lowercase, underscores/hyphens, max 48 chars. Unique per deck; if shared, unique across the container. | |
| action | No | Default 'write'. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Uniqueness, deck resolution and the skill allowance still run at write time (not_checked names them). | |
| shared | No | If true, skill is visible to vertical neighbours at boot. Container-context shared → specialized-contexts inherit. Specialized-context shared → container-context inherits. Default false. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| deck_handle | Yes | Handle of the deck this skill belongs to — must be a container-context or specialized-context deck | |
| description | Yes | Structured metadata for indexing and LLM dispatch | |
| container_id | Yes | Container ID | |
| raw_markdown | No | Full instruction body the LLM reads when the skill is invoked. May reference declared resources via {{ref:Name}} syntax. Omit to create a stub. | |
| signal_emission | No | Optional. Declares the signal this skill emits. The client AI fires write_signal at the declared point — run_pcd_skill surfaces it as an explicit emit_contract; the worker never auto-fires. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the basic mutation profile is already covered and the description is consistent with it. However, the description adds almost no behavioral context of its own — no mention of uniqueness/collision handling, shared visibility effects, or the validate/contract help modes that the schema documents. With annotations carrying the safety profile, a 3 reflects a description that adds little beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed immediately by the alternative. No filler, no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter mutation with nested objects and no output schema, the rich schema covers argument meaning but the description says nothing about the return value (e.g., created skill identity/handle) or the validate/contract modes. The schema compensates for most of the parameter burden, leaving the description minimally adequate rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and nine parameters (including nested objects, enums, and detailed per-field docs for action, shared, triggers, data_refs, signal_emission) are all fully specified in the schema. The description contributes no parameter detail, so the baseline 3 is correct when the schema does all 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 gives a specific verb ('Create') and glosses the resource as 'a reusable working method ... a procedure preserved for future use,' so the agent knows it writes a persistent skill rather than invoking one. It explicitly names the sibling update_pcd_skill, distinguishing create from revise. It stops short of 5 only because the domain term 'PCD Skill' is left as-is without tying it to other create_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear trigger ('when the user wants a procedure preserved for future use') and routes revisions to update_pcd_skill, which is genuine alternative guidance. It doesn't state exclusions or when to prefer list_pcd_skills/run_pcd_skill, so it lacks the explicit when-not coverage that a 5 requires.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare supported objects with saved versions.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | No | Deck load handle — alternative to object_id for decks; for container, resolves to that deck's container. | |
| version | No | Version number to compare against; a deck number resolves to its commit. Omit to compare against the newest saved version (for a deck, possibly a pre-update snapshot). For container, names the OLDER snapshot the latest is compared against; omit for latest vs previous. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| object_id | No | UUID of the object (deck_id, console_doc id, container_id, or skill id). Required for console_doc and skill; optional for deck and container when handle is provided. | |
| object_type | Yes | Type of object to diff |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond restating the purpose: it omits what a comparison returns, how versions are resolved, or the meaning of the 'contract' help mode (left entirely to 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?
A single tight, front-loaded sentence with no wasted words. It is efficient, though arguably too terse for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with full schema coverage the description is minimally adequate, but with no output schema the agent gets no sense of what the diff result contains, and 'supported objects' is never clarified. The heavy lifting falls entirely to structured fields.
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 provides zero additional parameter meaning beyond what the schema already documents for handle, version, contract, object_id, and object_type.
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 verb 'compare' with the resource 'objects' is present, but 'supported objects' is vague and never names the actual types (deck, console_doc, container, skill) that the schema enum reveals. It does not distinguish itself from version-related siblings like restore_version or commit.
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 when-to-use guidance, no prerequisites, and no alternative named. An agent cannot tell from the description when diffing is preferable to restore_version or read_deck for inspecting changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find knowledge records by topic or filters when answering a question or locating a reference. Returns candidate summaries and IDs; use read_knowledge for evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Filter by tags — records must contain all listed tags. | |
| limit | No | Max records to return (default 50, max 100). | |
| query | No | Nonblank query selects bounded search; omit for cursor-paginated listing. Query mode rejects cursor. All filters apply before matching and limiting. | |
| cursor | No | Pagination cursor — pass the previous response's next_cursor to fetch the next page. | |
| domain | No | Filter by domain — from the manifest's declared domains. | |
| status | No | Filter by status. Omit + include_drafts=false to get live records only (published + decided). | |
| category | No | Filter by category — e.g. 'decision', 'reference', 'manual', 'milestone', 'note', 'flow'. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | Yes | Container ID — required. Knowledge records are container-scoped. | |
| include_drafts | No | Include draft records in results — default false. | |
| cross_container | No | Aggregate read over your own account — drops the container filter and lists records across all containers you own, each row annotated with its container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error. | |
| include_superseded | No | Include superseded records — default false. Use true when walking a decision chain. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered, and the description adds behavioral value beyond that: it discloses the return shape ('candidate summaries and IDs') and the two-step find-then-read workflow. It does not mention rate limits or the cross_container gate, but the output-format disclosure is meaningful additional context.
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, front-loaded with the core purpose and immediately followed by the sibling routing. Every clause earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description compensates by stating what is returned (summaries and IDs) and how to proceed (read_knowledge for evidence). Combined with 100% schema coverage over all 12 parameters, the definition gives an agent everything needed to invoke it correctly; remaining gaps (e.g., pagination mechanics) live 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% with 12 fully documented parameters (cursor, tags-all semantics, contract help mode, cross_container gate, etc.), so the schema carries parameter meaning. The description only gestures at 'topic or filters' and adds no syntax or format detail beyond the schema, 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 and resource ('Find knowledge records') plus the means ('by topic or filters') and explicitly distinguishes itself from the sibling read_knowledge by scoping each to a different job. An agent can tell this is a discovery/search tool versus an evidence-retrieval tool 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?
Gives clear usage context ('when answering a question or locating a reference') and names an alternative (read_knowledge) with the condition that selects it ('for evidence'). Lacks explicit when-not-to-use exclusions, but the routing guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect deferred conditions and their progress. Use for outstanding findings; read_topology holds current work.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Scope the read to specific signal ids (e.g. picked from a titles scan) — container-guarded; unknown or cross-container ids are rejected with missing_ids, never a silent partial. When present, status defaults to 'all' so a just-resolved pick still reads. | |
| handle | Yes | Deck handle — used to resolve the container | |
| status | No | Filter by signal status — defaults to 'open' ('all' when ids are passed). 'all' returns every status. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| projection | No | Response grain — default 'full'. 'count' → { total, open, by_severity, by_assigned }: the cheapest triage headline. 'titles' → enriched triage rows { id, severity, title, assigned_to, signal_type, occurrence_count } — self-sufficient for a severity/owner table, no content. 'full' → the complete v2 payload incl. content + the updates[] ring. Lean-then-fetch: titles scan → pick ids → projection='full' with ids. | |
| assigned_to | No | Filter to signals routed to one deck handle — the routed read for deck-scoped surfaces. Omit for the full container queue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already establish the safety profile, lowering the bar. The description adds context that signals are deferred/outstanding conditions, but it does not describe response shape or edge cases; no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core action is front-loaded, and the sibling-routing clause earns its place by preventing a wrong tool choice.
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 detailed schema and read-only annotations, the definition is nearly complete: it supplies the business context that structured fields cannot. The only minor gap is that the description itself does not summarize the returned payload, though the projection parameter effectively fills this in.
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?
Parameter descriptions in the input schema cover 100% of the parameters and are unusually rich (e.g. ids container-guarding, projection grain, status defaults). The tool description itself adds no parameter-level meaning, 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 action ('Inspect') and a specific resource ('deferred conditions and their progress'), immediately clarifying what signals are. It also distinguishes from the sibling read_topology by saying that tool 'holds current work'.
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 recommends this tool for 'outstanding findings' and points to read_topology for current work, giving both a when-to-use and a when-not-to-use signal. This is sufficient routing even without opening the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify the authenticated account and its deck/container associations, or list decks within one container. Does not enter or change context.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | account returns authenticated identity and deck/container associations without entering context; container lists decks for exactly one selector. | |
| handle | No | Deck handle identifying a container; alternative to container_id. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container selector. Supply this or handle in container scope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the explicit behavioral guarantee that it does not enter or change the current context. This is useful context above the annotations and clearly signals a side-effect-free operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the primary purpose, followed by a useful non-operation caveat. It does not waste words, though it could name siblings slightly to sharpen routing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list/identity tool with full parameter documentation and no output schema, the description covers the key inputs, the two modes, and the non-mutating behavior. The main missing piece is explicit detail about return shape, but that is not required here given the tool's simplicity and 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%, so the parameters themselves are fully documented. The tool description restates scope behavior but does not add significant new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource pair: identify the authenticated account and its deck/container associations, or list decks within one container. It also explicitly says it does not enter or change context, which distinguishes it from siblings like switch_deck and resolve_container.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the two use cases: account-level identity and container-level deck listing. It also includes a when-not signal by saying it does not enter or change context, but it does not name alternatives or edge conditions beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find an existing working method before improvising a substantial procedure. Compare summary and when_to_use; fetch the chosen method with run_pcd_skill.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Calling deck's load handle (e.g. 'research') — resolves deck + container and scopes the manifest | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container ID — disambiguator when the same handle exists in more than one container |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already indicates no side effects, and the description does not contradict it. However, the description adds no behavioral detail beyond the annotation, so it meets the baseline but does not enrich transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but poorly structured. It mixes instructions for the user with an unclear reference to another tool, making it verbose in meaning while lacking clarity. It could be more concise and direct about listing skills.
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 does not explain what the tool returns (e.g., a list of skills with summaries). It implies comparison of summary and when_to_use but never explicitly states the output format. Given no output schema, this is a significant 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 schema covers 100% of the parameters with descriptions (handle, contract, container_id). The tool description does not add extra meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description does not state that this tool lists PCD skills. Instead, it gives meta-advice about finding a working method, comparing summary and when_to_use, and fetching with run_pcd_skill. This is misleading and does not match the tool name 'list_pcd_skills'.
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 references run_pcd_skill as a way to fetch a chosen method, but it does not clearly explain when to use list_pcd_skills versus its siblings. The guidance is implicit and confusing, lacking explicit conditions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enter a container, specialist scope or Console. Use switch_deck for an in-container scope change; reground restores faded instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Load handle e.g. research, writing, console | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container ID — required when user has multiple containers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose side effects, permissions, or behavioral outcomes. It is not clear whether load_deck modifies state, changes context, or has any impact beyond loading. Annotations indicate non-read-only and non-destructive, but the description adds no transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but the structure is muddled, mixing the unclear main action with alternative tool references. It is not concise in meaning, though length is acceptable.
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 lacks essential context: what a 'deck' is, what 'loading' entails, what 'container' or 'specialist scope' refer to, and how this tool fits into the overall workflow. Given the tool's apparent significance, the description is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (handle, contract, container_id all described in the schema). The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Enter a container, specialist scope or Console' does not clearly state what the tool does. The verb 'enter' is ambiguous, and the concepts of 'specialist scope' and 'Console' are undefined, leaving the purpose highly unclear.
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 mentions alternatives (switch_deck, reground) and what they are used for, but does not specify when to use load_deck itself. This provides partial disambiguation but lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initialise or maintain the knowledge corpus: manifest, domains, indexes, verification and template audits. Use write_knowledge to author record content.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Domain name — required for add_domain / remove_domain. | |
| action | Yes | describe: read manifest · ages: per-record days since verified_at — a pure date delta, no threshold or verdict; apply your own cadence on top · refresh_index: rebuild knowledge-index · refresh_manual_index: rebuild manual-index · add_domain / remove_domain: manage declared domains · verify: batch-refresh verified_at on record_ids · audit_templates: check records against their category's template; emits a signal per finding (deduped) and returns them. · initialise: idempotently initialize the corpus; accepts only container_id. | |
| category | No | Category filter — optional for audit_templates and ages (e.g. "manual" to scope to manual records). | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| record_ids | No | Array of record UUIDs — required for verify. | |
| description | No | Domain description — optional for add_domain. | |
| container_id | Yes | Container ID — required. Scopes all operations. | |
| include_drafts | No | Include draft records — optional for audit_templates (default false: live records only). | |
| include_superseded | No | Include superseded records — optional for audit_templates (default false: current records only; superseded ids retired by a newer record are excluded). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false), so the description is only expected to add side-effect context. 'Initialise or maintain' signals mutation but does not disclose what refresh_index, verify, add_domain, or remove_domain actually change or require, and no such details are supplied.
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, no filler, with the primary purpose front-loaded and the sibling routing placed second. Every word contributes to orienting the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-complexity dispatcher with nine actions, nine parameters, and no output schema, yet the description offers only an umbrella statement and one sibling rule. An agent still needs to infer when to run initialise vs refresh_index vs verify and what each action accomplishes, which the schema does not fully compensate for.
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 and the description need not repeat parameter docs. The description's list (manifest, domains, indexes, verification, template audits) loosely maps to the action enum values, but it adds no parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource ('knowledge corpus') and verbs ('Initialise or maintain'), and lists the operational areas: manifest, domains, indexes, verification, template audits. It also distinguishes itself from the sibling write_knowledge by routing content authoring to that tool, though it does not explicitly contrast with read_knowledge or find_knowledge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides one clear alternative: 'Use write_knowledge to author record content.' However, it does not state when to prefer manage_knowledge over read_knowledge/find_knowledge, nor does it give selection context for the nine action variants, so an agent must infer when to call the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update work and annotations or record a completion. Describe before composing unfamiliar operations.
| Name | Required | Description | Default |
|---|---|---|---|
| op | No | Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): what/goal/state/next/blocker are capped at 120/250/600/250/600 chars (a lookup what is never capped) and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send. | |
| action | Yes | Required. describe: returns the contract envelope (op catalogue, per-op payloads, server-side caps, parallel-safe property) — use as a pre-flight before composing a patch. validate: pre-send check — runs required-field + char-cap validation on a candidate op + payload WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? } so a long compose is checked in one cheap call instead of paying a rejected write to learn a length. State-dependent checks (item existence, group capacity) still run at write time. patch: applies one op against state. Pre-flight pattern: describe → choose op → (validate when composing long) → patch. | |
| payload | No | Required when action='patch' or 'validate' (validate takes the same candidate payload the patch would send). Ignored when action='describe'. Op-specific payload. work_patch: {what, patch: {goal?, state?, next?, assigned_to?, refs_append?: [...]}} — partial merge on the item matched by `what` (any group); provided fields update, untouched fields survive; refs_append appends to refs[] (exact duplicates skipped with a warning); empty or unknown-field patches are rejected with the patchable field list (`detail` rejects — renamed to `state`). `state` REPLACES — write the new standing from scratch, never the old text plus a layer; goal/state/next reject over 250/600/250 chars. Each appended ref is {kind, label?, locator}: kinds are knowledge | skill | signal | connection | url | file, the locator is the one its kind needs, and nothing else is accepted; the merged refs[] caps at 8. Stamps item.updated (the freshness clock behind the boot hygiene flags). assigned_to soft-validates like work_upsert. work_upsert: {group: 'active'|'paused'|'blocked'|'done', item: {what, goal?, state?, next?, refs?: [{kind, label?, <locator>}], annotations?, assigned_to?, ...}} — `detail` is rejected (renamed to `state`, topology 3.0); blocked requires `blocker`; done auto-stamps `closed` if missing; item.updated stamps on every upsert. Caps: active/paused 5, blocked 3, done 5 — over-cap on active/paused/blocked is REJECTED with a make-room hint (work items are never silently evicted); done alone trims oldest-by-closed. assigned_to is an advisory deck handle: soft-validated against the container's decks, mismatch warns in the envelope, never rejects. The sent item is checked against the work-item caps and ref shape; knowledge/skill/signal refs must resolve in this container, and a connection ref naming nothing the container declared warns and lands. work_transition: {what, to: 'active'|'paused'|'blocked'|'done', patch?: {...}} — transitioning to blocked requires `blocker` in patch; moving into a full active/paused/blocked group is REJECTED (make room first — the source item stays put), done trims oldest-by-closed. Only the patch you send is checked against the caps and ref shape — the stored item's other fields are left alone, so a bare transition of a legacy over-shape item passes. work_remove: {what}. work_annotate: {what, type, text: string|string[], actor?} — `what` matches the work item's `what` field (the same item key as work_patch/work_transition/work_remove); `type` is open vocabulary (gotchas, choice, observation, shipped, attempt, risk, …); `text` is the annotation content, aligned with did_append. Char caps (150 chars/bullet, 900 total) are REJECTED over-cap with a field+limit message (never truncated) — tighten and resend; the 6-bullet cap drops oldest. Per-item cap 10: an over-cap append succeeds and RETURNS the evicted annotation in evicted_annotations (annotations are memory, never silently destroyed) — graduate it to knowledge or fold it into the item if it still matters. did_append: {text, work_ref?, by?} — record a COMPLETION into the did trail (topology 3.0): `text` ≤250 chars (rejected over-cap); optional `work_ref` (a work item's `what` this completion closes) and `by` (your deck handle). Append-only, retention keep-everything; boot ships a tail of 8, read_topology pages deeper (trail='did'). A work_ref still in active/paused returns a nudge. Use for finished things — in-flight standing stays on the work item's `state` via work_patch. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | Yes | Container ID — required. Per-container Durable Object isolate serialises writes — parallel patch_topology calls for the same container queue inside the DO; calls for different containers run in independent isolates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the lower bar applies. The description nonetheless adds almost no behavioral context of its own — nothing about caps, rejection/truncation behavior, annotation eviction, or soft-validation, all of which live only in schema property text.
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 main purpose front-loaded and a secondary procedural hint following. No wasted words, though it is arguably terse for a five-parameter, nested-payload mutation 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?
The very detailed schema and 100% parameter coverage compensate for the description's brevity, and no output schema exists so return values need not be covered. However, the description leaves the tool's relationship to siblings like read_topology, team_work, and commit unstated, which is a real routing gap for such a complex write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the five parameters (op, action, payload, contract, container_id) including enum semantics. The description contributes nothing parameter-specific, which is the expected baseline 3 when the schema carries the full load.
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 set — 'Update work and annotations or record a completion' — which is clearer than the name 'patch_topology' alone, since the tool actually performs work-item ops, annotations, and did-trail appends rather than generic topology patching. It does not name the read counterpart (read_topology) or other plausible siblings (team_work, commit), so 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?
The only guidance is 'Describe before composing unfamiliar operations,' which hints at the describe pre-flight but does not say when to use this tool versus team_work, commit, or write_knowledge. The richer describe → validate → patch pattern lives in the schema, not the description, so routing guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a deck’s stored definition or saved version without entering it. Use load_deck or switch_deck to work in its scope.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | No | Deck load handle — e.g. 'writing'. Provide handle or deck_id. | |
| deck_id | No | Deck UUID. Provide handle or deck_id. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Optional disambiguator. Required when handle resolves to multiple rows (system-deck loads like 'container-meta' or 'user-meta' repeat across containers; specialized-context / container-context loads are account-unique and don't need it). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already present, the description still adds useful behavioral context by clarifying that this operation does not enter the deck's scope — it is a pure inspection. This is a meaningful non-mutating behavioral signal beyond the annotation. It does not detail return format, but that is not a glaring gap for a read-only inspection 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 with no wasted words. The purpose is front-loaded, and the alternative routing is compactly placed in the second sentence. Every piece earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a read-only inspection tool: it states what is inspected, clarifies that the tool does not enter scope, and points to the right alternative tools. The schema already covers all parameters, so the only minor gap is the lack of any indication of return shape, which is softened by 'stored definition or saved version' implying the returned content.
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 provides 100% coverage, documenting handle, deck_id, contract, and container_id with inline descriptions. The tool description adds no parameter-specific information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action ('Inspect'), a specific resource ('a deck’s stored definition or saved version'), and a key constraint ('without entering it'). It clearly distinguishes this tool from the sibling load_deck and switch_deck tools by stating that those are for working in scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: inspect without entering a deck. It also names the alternatives and the condition for selecting them: 'Use load_deck or switch_deck to work in its scope.' This leaves little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List submitted platform feedback or retrieve particular reports.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Batch read — feedback row ids from read_feedback without IDs; returns { feedback: [rows], count, ids_filter } in one response, rows field-identical to the single form. Any absent or not-visible id rejects the WHOLE call with missing_ids[] (no silent partials). No hard cap, but full rows average ~2.3KB — batch in 10-15s on a large sweep rather than sending the whole inbox at once. | |
| kind | No | Filter by feedback kind (bug | feature | support | session). | |
| status | No | Filter by status — defaults to open. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| feedback_id | No | Feedback row id from read_feedback without IDs — the single-item read, returns { feedback: row }. Pass either this or ids[], not both. | |
| container_id | No | Filter to one container — useful on the platform inbox. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=true and openWorldHint=false, so the description does not carry the full burden for safety. It adds a small amount of context by stating that the tool lists handled feedback or fetches a report, but it does not disclose behaviors such as failure semantics, pagination, or rate limits, although the parameter schema describes much of that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that conveys the tool’s core behavior in two clear branches. No filler, redundant phrasing, or scaffolding is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is compact but adequate because the input schema is exceptionally detailed, including return shapes, batch behavior, missing-id rejection, and default status. The one-sentence description does not need to restate those details; it might only lose minor points for not summarizing the contract mode or container filtering at a high level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully explains ids, kind, status, contract, feedback_id, and container_id. The description only loosely maps to the list-vs-single variation and adds no parameter meaning beyond what the input schema documents, so the high-coverage baseline applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear action-resource pair: listing or retrieving platform feedback, with an explicit distinction between list-style access and single-report retrieval. This is sufficient to distinguish it from the analogous write_feedback sibling even without naming it.
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 two usage modes (list all vs retrieve particular reports) are implied by the wording, and the counterpart write_feedback is inferable from the sibling list. However, the description does not explicitly say when-not-to-use this tool, name an alternative, or explain the selection between ids and feedback_id beyond what the schema already covers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve knowledge bodies, outlines or selected sections by record ID, or one flow stage with its routes, gates and skill.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Alias for record_ids — same shape, same semantics; use either. record_ids wins when both are passed. | |
| stage | No | Flow stage read: the stage's id or name. Needs exactly one record id — a flow — and handle. Returns the stage as written, its declared routes with their conditions, the flow's Gates, Resumption and Records, and the stage's skill as run_pcd_skill returns it from handle. Not with projection, sections or cross_container. | |
| handle | No | Only with stage: your active deck's handle. The stage's skill is read from this deck exactly as run_pcd_skill reads it. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| sections | No | Section-addressable read — fetch only the named sections instead of the whole body. Requires exactly ONE record_id. Same addressing as the patch surface: a bare level-2 slug returns that section's subtree (intro + level-3 children); a compound 'parent/child' slug returns just that level-3 sub-section. Unknown slugs are rejected with available_sections listed (no silent partial reads). Response items carry { slug, header, level, hash, markdown } + raw_chapter_hash — hashes flow straight into write_knowledge action='patch' expected_hash. Mutually exclusive with projection. Not with stage. | |
| projection | No | Response grain. 'full' (default) returns complete bodies — unchanged behaviour. 'summary' returns metadata + summary only, no raw_markdown — the cheap skim when you already hold ids. 'outline' returns metadata + section_tree (section slugs, headers, per-node hashes, word/paragraph counts — no bodies): the read twin of write_knowledge action='describe'. Lean-then-fetch: outline first, then sections for the parts you need. Not with stage. | |
| record_ids | No | Record UUIDs from find_knowledge without query or find_knowledge with query. Cross-container ids are rejected. Required unless `ids` is passed — `ids` is an accepted alias; record_ids wins when both are present. | |
| container_id | Yes | Container ID — required. Must match the container the ids belong to. | |
| cross_container | No | Accept ids from a cross-container browse/search by relaxing the same-container reject; records annotate their container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error. Not with stage. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description itself adds only mode enumeration; behavioral detail like unknown-slug rejection, hash handoff to write_knowledge, and cross-container gating appear in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that enumerates the read modes without filler. It is dense but every clause maps to a real capability; no wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with an output-free design, the one-sentence description is thin, but the 100%-covered schema and read-only annotations carry most of the missing context. Adequate but not self-sufficient.
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 parameter docs are extremely rich (aliases, mutual exclusions, hash flow, gates), so the schema does the heavy lifting. The description's mention of bodies/outlines/sections/stage maps onto the projection, sections and stage params but adds no semantics beyond them.
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 clear verb ('Retrieve') and enumerates the resources and modes: knowledge bodies, outlines, selected sections, or a single flow stage with routes/gates/skill. It implicitly separates the post-find retrieval case ('by record ID') from search siblings, though it never names find_knowledge 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?
The phrase 'by record ID' implies this is used after ids are obtained (i.e. after find_knowledge), which gives usable context. However, there is no explicit when-to-use/when-not statement, no mention of the alternative search tool, and the mutually-exclusive mode rules live only in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover and read user or assistant documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Chapter slug — required for read. | |
| action | No | categories → list available categories with audience + section_enum; index → list chapters in a category; read → return a single chapter body. Optional when slug is present — a {category, slug} call defaults to 'read'; a category-only call must pass action explicitly ('index' to list its chapters). | |
| section | No | Section — optional for read; required when category has multiple sections and slug is ambiguous (the tool returns the available sections in that case). | |
| category | No | Category slug — required for index/read. Currently: 'manual' (user manual) or 'ai-manual' (AI client manual). | |
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation makes the non-destructive nature explicit, and the description aligns with this by only mentioning discovery and reading operations. The contract parameter's description ('return the complete contract with no operation performed') adds transparency about a special no-op mode. No hidden side effects are indicated, and there is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The tool description is a single clear sentence, and the parameter descriptions are concise yet informative. There is no redundant or extraneous text. The structure is clean and easy to parse, with each parameter receiving a focused explanation.
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 and schema provide enough context to understand the tool's capabilities, including the available actions and categories. However, there is no output schema or explicit mention of the return format, which could leave some uncertainty about the exact response structure. For a read-only documentation tool, this is a minor gap rather than a critical omission.
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?
Every parameter is described in detail within the schema, including enum values, conditions, and current category slugs. The action description clearly explains the three possible values and their effects, and the contract parameter is explained with its no-op behavior. This goes well beyond minimal parameter names and provides actionable 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 clearly states the tool's purpose: discovering and reading user or assistant documentation. The resource ('manual') and verbs ('discover', 'read') are explicit, and the title reinforces this. It could be slightly more specific about the distinction between 'user' and 'assistant' documentation, but the core purpose 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?
The description implies usage through the action parameter ('categories', 'index', 'read') and the category values ('manual', 'ai-manual'), giving some contextual guidance. However, it does not explicitly state when to use this tool versus alternatives or mention any exclusions. The guidance is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read current work, a particular work item, or historical trails.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Paging — max entries to return (default 20, max 100). Ignored unless trail is set. | |
| trail | No | Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window. | |
| before | No | Paging — ISO timestamp; only entries with ts < before are returned. Pair with limit. Ignored unless trail is set. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| work_item | No | Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Takes precedence over trail when both are set. | |
| projection | No | Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes). | |
| container_id | Yes | Container ID — without trail or work_item, returns { projection, state } (see projection), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal). | |
| exclude_actions | No | Ops-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning. | |
| include_actions | No | Ops-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered, and the description adds nothing behavioral on top of that. Retention guarantees (keep-everything history), the warning behavior for misplaced filters, and the omission of worker_meta are all disclosed in parameter descriptions, not in the prose. The one sentence carries no behavioral context of its own.
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 names the three modes in order of specificity, with zero filler. It is appropriately tight, though it leans so terse that the mode-selection logic is left entirely to 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?
This is a complex nine-parameter tool with three read modes and no output schema, which would normally demand heavy description support. The extremely rich schema descriptions compensate by spelling out each mode's return shape and paging semantics, so the terse prose is defensible rather than 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 schema fully documents all nine parameters, including enums, defaults, precedence, and return shapes. The top-level description adds no parameter meaning beyond the fields, so the baseline 3 is the correct ceiling here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Read) and enumerates the three distinct read modes: current work, a single work item, and historical trails. That gives an agent a usable sense of what comes back. It stops short of differentiating from the sibling write counterpart patch_topology, so it is clear but not sibling-routing.
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?
Naming the three modes implies the three situations in which the tool applies, but the top-level sentence never states when to prefer one mode over another, what prerequisites exist, or which sibling handles the write side. The actual routing logic (work_item precedence over trail, projection grain) lives only in the schema, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recover the active operating instructions when context has faded; read_topology refreshes work state.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Your CURRENT deck handle — reground re-projects the frame you already hold. To enter a different deck, use switch_deck instead. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| sections | No | Targeted slices to re-pull, e.g. ['own/guidelines','container/out_of_bounds','user','voice']. Layer wholes (own/container/company/user), 'layer/field' compounds, and asides (grounding/voice/orientation/precedence). Unknown slug → reject with available_sections. | |
| projection | No | full (default) re-carries the whole frame; outline returns the layer/field map (counts + hashes, no bodies) for lean-then-fetch. Ignored when sections is set. | |
| container_id | No | Container ID — required when user has multiple containers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers the side-effect profile, and the description does not contradict it. However, the description adds no additional behavioral detail such as error cases, auth requirements, or state-change guarantees.
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 efficient sentence. The read_topology clause adds useful orientation without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided and the description only vaguely gestures at the result ('recover active operating instructions'). It does not specify what is returned or what the caller should expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with 100% coverage, so the baseline applies. The description proper adds no parameter-level information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear action ('Recover') and object ('active operating instructions'), with a trigger condition ('when context has faded'). It also references read_topology as a related sibling, though the precise boundary between the two is only lightly drawn.
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 a condition for use ('when context has faded') and nods to an alternative ('read_topology refreshes work state'), but it does not explicitly state when to prefer this tool over the alternative or mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a handle to its container without loading context.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Deck handle — e.g. 'research', 'writing'. Case-sensitive. | |
| contract | No | Help mode — return the complete contract with no operation performed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature is covered. The description adds the useful behavioral note that no context is loaded, but says nothing about return values, failure modes, or the effect of the contract help parameter, which is left to 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 a single, front-loaded sentence with no filler. It is concise and efficient, though slightly terse and reliant on domain jargon like 'container' and 'handle'.
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-param read-only tool, the description plus schema is minimally viable. However, it does not explain what a container is, what the resolve operation returns, or when to choose this over sibling deck/context tools, so an agent is left to infer some key context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'handle' and 'contract' already described in detail, including case-sensitivity, an example, and help-mode behavior. The description adds no paramerter-level meaning beyond what the schema already provides, 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?
The description uses a specific verb ('resolve') with a specific resource ('a handle to its container') and adds a meaningful constraint ('without loading context'). It does not explicitly differentiate from sibling tools like load_deck or read_deck, and 'container' is undefined, so it is not 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 phrase 'without loading context' implies this is a lightweight alternative to operations that would load context, but the description never states that explicitly nor names alternatives such as load_deck or read_deck. Usage is therefore implied rather than clearly instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a deck or skill from a saved version; platform maintainers may also restore console documents.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | No | Deck selector only; alternative to object_id. | |
| version | No | Saved version number; a deck number resolves to its commit. Supply exactly one of version or version_id. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| object_id | No | Object UUID; required except when a deck handle is supplied. | |
| version_id | No | Saved version UUID; alternative to version. | |
| object_type | Yes | Object to restore. console_doc is restricted to platform maintainers and commits a new version; deck and skill restore working content — commit separately. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds non-obvious behavior: console_doc restoration is restricted to platform maintainers, and deck/skill restores touch working content only and must be committed separately. That is meaningful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence covering the primary resources and the maintainer-only exception, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all three object types, the maintainer restriction, and the commit-separately caveat; the destructive overwrite semantics are left to the annotations, and there is no output schema to explain. Adequate, though a note on irreversibility of the working-content overwrite would round it out.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents handle, version, version_id, object_id, contract and the object_type enum. The description adds no parameter-level detail, 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 ('Restore') and resources ('a deck or skill ... console documents'), which an agent can distinguish from siblings like commit or update_deck. It does not explicitly name a sibling it is not, but the purpose 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?
The description says what restore does but gives no when-to-use guidance, no condition for choosing restore over commit/diff/load_deck, and no prerequisites. Usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a named skill’s instructions and resolved references for the assistant to follow. Does not itself perform the procedure.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Skill name — as listed by list_pcd_skills | |
| handle | Yes | Your active deck handle — used to verify access scope | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container ID — speeds up lookup, include if known |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly notes 'Does not itself perform the procedure,' which aligns with the readOnlyHint annotation. This reassures the agent that the tool has no side effects. While the annotation already conveys read-only behavior, the explicit human-readable statement adds clarity beyond the raw flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and free of fluff. It front-loads the core purpose and adds a critical caveat in the second sentence. No unnecessary words 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 indicates the output will be 'instructions and resolved references', giving the agent an idea of what to expect. It does not specify output format, error conditions, or permissions, but given the simple read-only nature and the presence of sibling list tools, the context is reasonably complete for invoking the 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?
All four parameters are described with useful context: name is 'as listed by list_pcd_skills', handle is 'your active deck handle', contract is 'Help mode — return the complete contract', and container_id is 'speeds up lookup, include if known'. These go beyond mere parameter names and provide actionable semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Retrieve a named skill’s instructions and resolved references.' This identifies the verb (retrieve) and resource (skill instructions). It also distinguishes itself from execution by adding 'Does not itself perform the procedure,' which separates it from any skill-running tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage ('for the assistant to follow') but does not explicitly state when to prefer this tool over siblings like list_pcd_skills or create_pcd_skill. No direct comparison or conditional guidance is provided, so the context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the active deck within an entered container.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | Deck handle to switch to e.g. research, writing — or the container-context handle to return to the top scope | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container ID — required when user has multiple containers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, which aligns with a state-changing operation. The description adds minimal behavioral detail beyond stating the action, lacking any mention of side effects or return values.
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, direct sentence with no redundant wording. It is highly concise and well-structured, containing only the essential information.
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 mutation tool, the description adequately explains the core operation. It does not explain expected return values or edge cases, but given the lack of an output schema and the tool's straightforward nature, the information is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the schema, covering 'handle', 'contract' (help mode), and 'container_id'. The descriptions are concise but sufficiently clarify each parameter's purpose, exceeding the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (change) and the resource (active deck within a container). It is distinct from sibling tools like load_deck or read_deck, though the term 'entered container' is slightly ambiguous without additional 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?
No guidance is given on when to use this tool versus alternatives like load_deck or read_deck. The description does not mention prerequisites or scenarios where switching decks is appropriate or inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enter a specific team environment or return to personal work while retaining the explicit personal setup.
| Name | Required | Description | Default |
|---|---|---|---|
| contract | No | Help mode — return the complete contract with no operation performed. | |
| destination | Yes | The active work environment after this call. | |
| team_container_id | No | Required only when destination=team; identifies the exact team destination. | |
| personal_container_id | Yes | Explicit personal-container anchor retained for the conversation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one behavioral fact — that the explicit personal setup is retained across the switch — which is genuinely useful. It does not, however, resolve the tension between a name that implies a state change ('switch/enter') and a readOnly annotation, nor does it mention side effects or what happens to the prior environment.
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 padding; the core action is stated first. The trailing clause 'while retaining the explicit personal setup' is slightly vague but earns its place as the only behavioral detail provided.
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 100% schema coverage and no output schema, the structured fields carry most of the load. Still, for a tool with a conditional required parameter and a 'contract' help-mode flag, the description is thin — it never mentions the help mode or the team_container_id requirement, and gives no guidance on return 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 all four parameters (contract, destination, team_container_id, personal_container_id) are already documented in the schema, including the conditional requirement on team_container_id. The description adds no parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a recognizable verb and resource: entering a team environment or returning to personal work. An agent can infer this is a context/environment switch. However, it never distinguishes itself from siblings like switch_deck or team_work, which also deal with context transitions.
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 'enter a specific team environment or return to personal work' — the agent can guess this is for moving between team and personal contexts. But there is no explicit when-to-use, no prerequisites (e.g. team_container_id required for team), and no named alternatives such as switch_deck or team_work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or advance shared work, publish versioned contributions, and request or respond to exact-version reviews in one permission-checked team destination.
| Name | Required | Description | Default |
|---|---|---|---|
| work | No | Work item on create_work, or a field patch on update_work/transition_work. what/goal/state/next/blocker are capped at 120/250/600/250/600 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped. | |
| limit | No | Result cap: read_reviews and list_documents default to 20 with maximum 50; search_documents defaults to 10 with maximum 20. | |
| query | No | ||
| title | No | ||
| action | Yes | Operation. Call describe before composing an unfamiliar contribution, work write, or document action; describe.document_actions is the action-specific contract. | |
| offset | No | ||
| reason | No | ||
| comment | No | ||
| content | No | ||
| summary | No | ||
| work_id | No | Stable shared-work UUID for update_work or transition_work. | |
| category | No | ||
| contract | No | Help mode — return the complete contract with no operation performed. | |
| revision | No | Immutable document revision to check with check_document; defaults to the current revision. It is not an optimistic write token. | |
| standing | No | ||
| record_id | No | Versioned Team record. Required by record- and document-specific reads and writes; inspect describe.document_actions for each document action. | |
| work_refs | No | ||
| feedback_id | No | ||
| to_revision | No | ||
| contribution | No | Structured immutable contribution body. Reviews are accepted only by respond_review and require basis.reviewed_version. | |
| raw_markdown | No | ||
| review_scope | No | read_reviews routing filter; defaults to requests open to the team or assigned to the caller. | |
| target_group | No | Required for create_work and transition_work. | |
| from_revision | No | ||
| review_status | No | read_reviews lifecycle filter; defaults to open. | |
| request_content | No | Review question or requested checks for request_review. | |
| source_revision | No | ||
| expected_revision | No | Current immutable record revision required for revise_contribution, mark_ready, revise_document, and submit_document. | |
| review_request_id | No | Review-request signal UUID for response or resolution. | |
| reviewed_revision | No | Exact ready proposal revision pinned by request_review. | |
| team_container_id | No | Exact team destination; required for every action except describe. | |
| assigned_member_id | No | Optional active owner/editor UUID; omit or null to open the request to the team. | |
| reviewed_record_id | No | Contribution record whose exact ready revision is being requested for review. | |
| expected_work_revision | No | Required optimistic version for every shared-work write. | |
| expected_request_revision | No | Optimistic request version required by resolve_review. | |
| expected_transition_revision | No | Current lifecycle transition revision required by contribution and document writes; open_document_round accepts this version but not expected_revision. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false and openWorldHint=false, and the description's only added behavioral fact is 'permission-checked' plus 'versioned contributions'. It does not disclose the mixed read/write nature of this single tool, that contributions are immutable once published, the optimistic-revision concurrency model, or which actions can alter stored state irreversibly — all of which matter greatly for a 26-action 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?
The prose itself is tight and front-loaded, but for a tool exposing 26 actions and 36 parameters a single sentence is under-specification rather than conciseness. Nothing is wasted, yet far too little is said relative to the surface area.
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?
This is the most complex tool in the set — 26 actions, deep nested contribution/work objects, no output schema, and revision-based concurrency — yet the description covers only the work/contribution/review slice and omits the entire document workflow, the required describe-before-write protocol, and the optimistic versioning requirements documented 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?
With 36 parameters and only 58% schema description coverage, the description is expected to compensate, and it does not: action, team_container_id, expected_work_revision, limit, and the various expected_*_revision tokens receive no explanation beyond the words 'versioned' and 'exact-version'. Those two words gesture at the revision-pinning contract but convey no usable semantics for the parameter set.
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 sentence names recognizable verb+resource families (read/advance shared work, publish contributions, request/respond to reviews) and scopes them to a 'permission-checked team destination', which distinguishes it from generic write tools. But the action enum contains 26 operations, roughly half of them document-related (create_document, submit_document, diff_document, give_feedback, close_round, etc.), and the description never mentions documents at all, so an agent cannot infer the tool's true remit from the description 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?
There is no when-to-use guidance and no routing away from siblings such as commit, write_knowledge, read_feedback, or write_feedback, all of which plausibly overlap with the review/contribution surface. The most valuable usage instruction ('call describe before composing an unfamiliar contribution, work write, or document action') lives in the action schema, not the description, so the description itself supplies essentially no decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revise a container or specialist deck configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| load | No | Change the deck's load handle (the boot key). Lowercase, hyphens allowed, max 24 chars, must start with letter or number, must not be reserved (meta/console/container-context), must be unique per user. Mirrored onto raw_json.load. | |
| name | No | Rename the deck (display name, max 64 chars). Optional — provide to rename. Mirrored onto raw_json.name. | |
| action | No | Default 'write'. 'validate': pre-send check across all three write surfaces (content field caps via the same enforceDeckCaps the write runs, content_ops op/field vocabulary, name ≤64, load format) WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Deck resolution, merged-content caps, and content_ops application still run at write time. No identifier needed for validate. | |
| handle | No | Alternative identifier — deck.load handle. Use when neither deck_id nor container_id is at hand. | |
| content | No | Partial content patch. Shape: intent (≤600), description (specialized-context only, ≤300 — container-context rejects it; intent is the container's single what-is-this answer), guidelines (instruction_item[]), out_of_bounds (instruction_item[]), data_refs, file_map. file_map is keyed by stable reference name; every item is { path: string, description?: string }, stays deck-local, and key-merges with existing (null deletes a key). instruction_item is { rule, priority, shared? } — per-item shared governs what flows to specialized loads (guidelines/data_refs opt-in via shared:true; out_of_bounds opt-out via shared:false). data_refs entries take optional declaration-layer knobs: read {projection: 'outline'|'summary' | sections: string[]} on medium='kb_record' (grounding grain) and routing 'pcd'|'direct'|'auto' on medium='mcp_connection' (broker vs client reach); a data_ref of type 'flow' points at a flow record — medium 'kb_record', never mandatory, no read knob, at most 3 per deck; rejected on other mediums. Most fields REPLACE on provided — prefer content_ops for single-item edits on the three arrays. session_modes retired — sending it rejects. Optional — may be omitted when only patching name/load. | |
| deck_id | No | Preferred identifier — deck UUID. Required for specialized-context (since multiple per container). | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| deck_type | Yes | User-editable deck type. Platform-managed types (container-meta, user-meta, company-meta) are NOT writable through this tool — they live behind their dedicated tools. | |
| content_ops | No | Per-item ops against the CURRENT stored arrays; no whole-array resend. Applied sequentially, first failure rejects the call (no partial application). A field addressed here must not also appear in content. The post-ops array flows through the same caps + knob validation as a whole-array write. | |
| container_id | No | Alternative identifier — container UUID. Only valid when deck_type='container-context' (1-per-container). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, and 'revise' is consistent with a mutation, so there is no contradiction. However, the description adds nothing beyond that: it does not mention the validate/contract help modes, the no-partial-application semantics, or the replace-on-provided behavior, all of which are disclosed only in 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?
A single front-loaded sentence with zero redundancy, which is good for conciseness. It is arguably too thin for a tool of this complexity, but as a pure sizing/structure judgment 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?
This is a high-complexity mutation tool (10 params, nested objects, nested content_ops, dual deck types) with no output schema, so the description carries some burden. The exceptionally rich schema fields compensate substantially for the one-line description, but the description still omits the identity-resolution fallback logic and the help modes needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all ten parameters in depth (load format, action modes, content shape, content_ops matching). The one-line description adds no parameter meaning at all, making the baseline 3 the correct score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('revise') and resource (deck configuration) and names the two deck types it operates on (container/specialist). It does not, however, distinguish itself from nearby siblings like create_deck, update_meta, or patch_topology, so the agent must infer the boundary from 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 no when-to-use, when-not-to-use, or alternative routing information. Critical guidance such as 'platform-managed types live behind dedicated tools' and the validate-vs-write mode selection appears only inside the parameter schema, not in the tool description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update account-wide user or company context.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Default 'write'. 'validate': pre-send check — runs the same per-surface cap validators the write path enforces post-merge (identity/preferences key + char caps, guidelines instruction caps) on the candidate payload WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. | |
| payload | Yes | Surface-specific payload. user → { identity?, preferences?, guidelines? }. company → { brand?, standards?, methodology? }. Object/dict fields are key-merged with existing; arrays REPLACE on provided. See schema doc §user-meta / §company-meta for shapes + caps. | |
| surface | Yes | Which meta surface to write. 'user' → the account's user-meta (identity/preferences/guidelines). 'company' → the account's company-meta (brand/standards/methodology). | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Optional nudge hint — if provided, bumps the container's topology freshness stamp so the current turn sees the change on next refresh. NOT a write target. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already supply readOnlyHint=false and destructiveHint=false, so the generic word 'update' adds no new behavioral insight. The description does not mention key behaviors such as key-merge versus array-replace, validation, or side-effects of the container_id hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler; the core surface distinction is front-loaded. It is as concise as possible with the given scope.
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 moderately complex with an alternative validate-only action, a help contract mode, nested payload structures, and merge/replace behavior, but the description communicates none of that. An agent cannot know from the description alone that this tool can validate without writing or that the schema documents critical limitations.
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 detailed descriptions for every parameter. The tool description itself adds no parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('update') and resource ('account-wide user or company context'), and the 'user' vs 'company' distinction maps to the surface enum. It stays at 4 rather than 5 because it does not explicitly differentiate this from sibling tools such as write_container_meta.
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, and no mention of the validate or contract modes. The phrase 'account-wide' implies scope, but the description lacks the explicit selection rules that would let an agent route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revise an existing skill’s instructions, discovery guidance or ownership; supports targeted patches. Use create_pcd_skill for a new method.
| Name | Required | Description | Default |
|---|---|---|---|
| echo | No | action='patch' only — opt-in post-write self-verification. When true, the response adds echo: [{ slug, header, level, hash, markdown }] with the post-write rendered section per touched node (paragraph ops echo their parent section); removals return { slug, removed: true }; rename_section returns the new slug + renamed_from. Default absent: response unchanged. Rejected on other actions. | |
| name | No | Rename the skill. Lowercase, underscores/hyphens, max 48 chars, must start with letter or number. Uniqueness re-checked per (container, deck) and per (container, shared). | |
| action | No | 'write' (default) — full-body replace + field edits, today's behaviour. 'describe' — pre-flight: returns the skill's section_tree (slugs + per-section hashes + addressing) for composing a patch; stub skills (no body) return section_tree: null. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing or reading the row; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. 'patch' — targeted section/paragraph edits via patches[] without resending the whole body; skills declare no section_schema, so only op guards apply (slugs, hashes, HEADER_IN_CONTENT, duplicate-slug, rename_section frame-free). | |
| shared | No | Toggle shared visibility. When flipped to true, name uniqueness is re-checked across all shared skills in the container. | |
| patches | No | Patch ops for action='patch' — same vocabulary and addressing as write_knowledge action='patch': replace_section / replace_section_intro / append_section / insert_section_after / remove_section / rename_section / replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Compose against the section_tree from action='describe'; content is BODY-ONLY (HEADER_IN_CONTENT); expected_hash per op for optimistic concurrency. Pass as JSON array; a JSON-encoded string is also accepted. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| skill_id | Yes | Skill UUID — required. | |
| deck_handle | No | Reassign the skill to another deck in the SAME container by load handle. Target must be a container-context or specialized-context deck; name uniqueness is re-checked against the target deck. Works with action='write' (the default). | |
| description | No | Replace the description object when provided. Must include summary + when_to_use. data_refs[].ref_name is a declared binding resolved against the skill's EFFECTIVE deck in order: own data_refs, own file_map, container-context data_refs. Container file_map never flows; shadowed declared names return a warning. triggers[] declares the PCD tool names after which this skill should surface as a one-line hint; see create_pcd_skill for the semantics. | |
| raw_markdown | No | Replace the skill body (markdown) when provided. | |
| signal_emission | No | Replace the skill's signal_emission when provided; pass null to clear it. See create_pcd_skill for the shape. | |
| expected_chapter_hash | No | Optional whole-body concurrency guard for action='patch' — the raw_chapter_hash from action='describe'; mismatch rejects before any op runs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses substantial behavior: full-body replacement, targeted patching, pre-flight describe, non-writing validate, concurrency guards, uniqueness re-checks, and section removal operations. There is no contradiction with the readOnlyHint and destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but appropriately structured and dense with relevant detail. Every parameter description adds meaningful guidance, and the nested objects are explained clearly without irrelevant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers return shapes for describe, validate, echo, and contract modes, which is helpful given there is no output schema. It is slightly less explicit about the success output for the default write action, but overall it provides enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the descriptions add significant semantic detail for each parameter, including action-specific behavior, patch op vocabulary, deck-handle constraints, description resolution order, signal-emission shape, and concurrency hashes. This goes well beyond the raw 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 title and description clearly state that this tool updates an existing PCD skill, and explicitly directs users to create_pcd_skill for new skills. This distinguishes it from the sibling create and 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?
The description clearly indicates when to use this tool versus creating a new skill, and the action parameter explains distinct usage modes like describe, validate, patch, and write. This provides strong contextual guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add progress, reassign, resolve or dismiss an existing signal.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | One line, ≤ 150 chars — the reassign reason or the progress/context note. Over-cap is REJECTED, never truncated. | |
| action | Yes | note/reassign require handle and note; reassign also needs assigned_to. resolve/dismiss close the signal, with optional outcome. Progress never closes implicitly. | |
| handle | No | Your active deck handle — stamps `by` on the trail entry | |
| outcome | No | How it ended — e.g. acted/ignored for propositions, pass/fail for checks. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| signal_id | Yes | UUID of the open signal to update | |
| assigned_to | No | Target deck handle — required for action='reassign', invalid otherwise. Soft-validated: an unknown handle warns, never rejects. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description complements by stating actions like 'resolve or dismiss', which convey state changes. It does not disclose subtle side effects (e.g., notifications, cascading updates), but the primary behavior is clear and consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly communicates the tool's function without fluff or redundancy. It is well-structured for quick comprehension.
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 does not specify the return value or success/error behavior for normal operations, but it does mention the 'contract' parameter for help mode. Given the tool's simplicity and the absence of an output schema, the lack of detailed return info 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?
Schema descriptions cover all 7 parameters with detailed constraints (e.g., 'Over-cap is REJECTED, never truncated', 'invalid otherwise', 'Soft-validated'). The tool description itself adds no parameter meaning beyond what the schema already provides, 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 clearly states the tool's purpose: 'Add progress, reassign, resolve or dismiss an existing signal.' It names the resource (signal) and the specific actions, distinguishing it from tools like write_signal (likely for creating signals) and get_signals (for listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing signal and lists action variants, but it does not explicitly contrast with sibling tools like write_signal or get_signals. The intended conditions are reasonably inferred from the phrasing, though a more explicit when-to-use would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Maintain the container specialist roster.
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | Default 'write'. 'validate': pre-send check — per-item required roster fields + the ≤300 description cap — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| specialists | Yes | Compiled context entries — one per committed specialized-context in the container. Roster fields locked: load (boot key), name (display), description (≤300 char summary), status, use_when (when to enter this context), do_not_use_when (when to stay out). | |
| container_id | Yes | Container ID to write container-meta for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description and action mode explain that normal use writes, while validate and contract modes explicitly do not perform writes, which is transparent for a write-capable tool. It does not clarify whether writing replaces or merges the existing specialist roster, so some behavioral detail is still missing.
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 overall definition is compact and the schema-level descriptions are well structured without unnecessary verbosity. The top-level description, however, is very terse and adds little beyond the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The validate and contract modes describe their expected outputs, but the normal write response, error behavior, and whether the specialists array replaces or merges existing entries are not documented. Given the complex array payload and lack of an output schema, these gaps matter for a caller.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are described with meaningful semantics beyond their names: container_id indicates the target container, specialists are described as compiled context entries with locked roster fields, and action/contract explain modes and expected behavior. Schema coverage is complete and descriptions add real value.
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?
Tool title and first sentence indicate maintenance of a container specialist roster, but 'Maintain' is not a precise verb and the tool's full purpose only becomes clear from the schema's action and specialists descriptions. It does not explicitly differentiate itself from sibling tools such as update_meta.
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 action parameter gives useful guidance for 'write', 'validate', and 'contract' modes, including that validate performs no writing. However, there is no explicit guidance on when to choose this tool over alternative sibling tools or when a caller should prefer one mode over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a structured platform bug, feature or support report.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Feedback kind — bug | feature | support | session, per the feedback manifest. Each kind has its own section template. | |
| refs | No | Optional rich pointers, same shape as signal refs, e.g. [{kind:'deck', handle:'…'}, {kind:'file', path:'…'}]. | |
| action | No | Default 'write'. 'describe' + kind returns the kind's section contract (names, required flags, caps, hints) without writing — the pre-flight before composing a report. 'validate': pre-send check — runs the kind template's section validation (required sections, max_length caps) on a candidate content WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}] }. | |
| content | No | Filled template sections keyed by section name — required for write, ignored on describe. Required sections must be present; over-cap content is rejected with the limit named, never truncated. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| container_id | No | Container where the feedback is raised — required for write, not needed on describe. The platform's resolution comes back as a signal into this container. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark readOnly=false and destructive=false, and the description clearly indicates writing only for the write action while describe/validate are no-write. It also explains that container_id is required for write and that the resolution returns as a signal. It does not explicitly state persistence or failure behavior, but side effects are generally clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main description is concise and front-loaded, while detailed mode and parameter behavior are placed in field descriptions where they belong. The wording is dense but not redundant, though some field descriptions repeat 'required for write' in multiple places.
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 no output schema, the description covers input requirements, mode behavior, validation return shape, and the signal resolution for container_id. It does not specify the success response for write beyond the signal resolution, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Every parameter has an informative description that goes beyond basic schema types: kind lists allowed values, action explains each enum behavior, content distinguishes required-on-write and cap rejection, and container_id explains when it is required and what happens with resolution. This fully equips an agent to populate inputs.
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 clear verb-object statement: 'Submit a structured platform bug, feature or support report,' which distinguishes it from read_feedback and other siblings. The title and description align, and field-level details clarify that it is for structured report creation.
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 specifies mode-specific behavior: describe returns the contract, validate pre-checks content without writing, and write is the default; contract is help mode. However, it does not explicitly contrast with sibling tools such as write_signal or update_signal, so some inference remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, revise, patch or supersede durable knowledge. Describe its required shape before composing.
| Name | Required | Description | Default |
|---|---|---|---|
| echo | No | action='patch' only — opt-in post-write self-verification. When true, the response (patched AND supersede-by-delta) adds echo: [{ slug, header, level, hash, markdown }] with the post-write rendered section per touched node (paragraph ops echo their parent section); removals return { slug, removed: true }; rename_section returns the new slug + renamed_from. Default absent: response unchanged. Rejected on other actions. | |
| slug | Yes | Unique slug for the record. Must match the category's slug_format (see manifest). | |
| tags | No | Tags as an array of strings — pass as JSON array ["a","b"] or comma-separated string. | |
| title | No | Record title. Required on create (validated against the category's template metadata); optional on update. | |
| action | No | Pre-flight, pre-send check, full write, or partial patch. 'describe' returns the category contract + per-record state — no body required. 'validate' runs the exact write-path validation (slug format, status, immutability, template sections, metadata, summary max_length) on a candidate payload WITHOUT writing — for a flow, its stage structure too — returns { valid, missing_required[], over_cap: [{field, len, cap}] }; use it before committing a long compose so an over-cap field costs one cheap check, not a rejected write. Default 'write' commits in one call. 'patch' applies targeted section/paragraph edits to an existing record via `patches[]` without sending the whole body — supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) the patch reconstructs the successor and supersedes (returns action='superseded'); on mutable categories (manual, reference, note, flow) it edits in place (action='patched'); on a flow the stages are re-checked on the patched body first. Pre-flight with describe to fetch the current section_tree + hashes. | |
| domain | No | Domain — optional. If supplied, must be declared in the manifest's domains block. | |
| status | No | Status. Must be one of: the category's default_status, 'draft', a declared live_state, or 'archived'. Transitioning into a live_state fires the manifest's on_promote side-effects. | |
| patches | No | Array of patch ops for action='patch'. Level-2 ops: replace_section / replace_section_intro / append_section / insert_section_after / remove_section. Level-3 ops: replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Both levels: rename_section — { section_slug, new_header, expected_hash? } renames a heading + its slug without resending the body; body and children untouched, child slugs cascade on a level-2 rename; required frame sections reject (REQUIRED_SECTION), slug collisions reject (DUPLICATE_HEADER). Section slugs are doc-local addressing, not a stable cross-doc contract — a rename that changes a slug raises a repair signal for cross-record references (warning in the response). Addressing: level-2 ops take section_slug=<bare slug> (insert_section_after takes after_section_slug). Level-3 ops take section_slug=<parent's BARE slug> PLUS the child's compound 'parent/child' slug in paragraph_slug (after_paragraph_slug for insert_paragraph_after) — never put the compound slug in section_slug (exception: rename_section on a level-3 child takes the compound slug directly in section_slug); append_paragraph / prepend_paragraph create a new child under section_slug=<parent> with the title in header. See section_tree.addressing in the describe response. Each op also carries content/header as applicable. content is BODY-ONLY: never include the section's '## …'/'### …' heading line — the heading is emitted from the slug (replace ops) or the header param (append/insert ops); a content opening with a heading line is rejected with HEADER_IN_CONTENT. Ops without a header param reject a stray header field (UNEXPECTED_HEADER) — renaming goes through rename_section, never a header on replace_section. replace_section_intro edits ONLY a level-2 section's own lead text and preserves its level-3 children — use it to fix a parent section's intro when it has subsections (replace_section refuses such a section with CHILDREN_PRESENT). replace_section / replace_section_intro / replace_paragraph / remove_paragraph / rename_section accept optional expected_hash for optimistic concurrency. Pass as JSON array; the worker also accepts a JSON-encoded string. Supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) a patch reconstructs the successor and supersedes rather than editing in place. | |
| summary | No | Short summary (used as the stage-1 search summary). Required on create per most category templates; optional on update. | |
| audience | No | Audience — defaults to internal. | |
| category | No | Category — must be declared in the manifest (note, decision, reference, manual, milestone, flow). 'knowledge' is reserved. Immutability + locking are derived from the manifest's transitions on promotion. A record never moves into or out of 'flow' — write a new record instead. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| supersede | No | Supersession-with-shared-slug. When true, the call retires the canonical immutable record at this slug and atomically writes the successor in its place at the same slug. Required: full body fields for the successor (raw_markdown, title, summary, etc.) per the category template. The slug must already hold an immutable record; otherwise the call errors. Use this on a decision rewrite, not on a routine update. | |
| container_id | Yes | Container ID — required. Scopes the record to the correct container. | |
| raw_markdown | No | Full content in markdown. Validated against the category's template sections. Optional on update — omit to keep the existing body. Pre-flight with action="describe" to fetch the category-specific contract (slug format, required sections, metadata caps, on_promote effects) before composing. | |
| superseded_by | No | UUID of the record that supersedes this one. Sets the chain pointer on an immutable record (chain-pointer-only path; no body fields). For supersession-with-shared-slug — retiring an immutable record and writing its successor at the same canonical slug — use `supersede: true` with full body fields instead. | |
| expected_chapter_hash | No | Optional chapter-level hash for optimistic concurrency. If provided and the chapter has changed since you computed it, the patch is rejected with a re-read tip. Get the current value from describe response's section_tree.raw_chapter_hash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this mutates local state without external side effects. The description adds the describe-first workflow and the supersede verb, but says nothing about immutability, in-place vs supersession behavior, permission needs, or the rejection/validation model — all of which live only in the schema. Supersession retires a canonical record, which sits in mild tension with destructiveHint=false, though the record is preserved for restore_version, so this is not a clear contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the verb set front-loaded before the workflow instruction. It is well-structured, though its extreme brevity is under-specification for a four-action, 17-parameter tool rather than model conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity — four actions (describe/validate/write/patch), immutable vs mutable category behavior, supersession, and patch addressing — the description omits the action model, immutability consequences, and sibling routing entirely. The unusually rich schema compensates for most parameter-level gaps, but the description itself does little to orient an agent before it opens 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% and the schema documents all 17 parameters in exceptional detail (action semantics, patch ops, supersede vs superseded_by, expected hash concurrency). The description adds only the "describe the required shape first" hint and no parameter-level meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names specific verbs (create, revise, patch, supersede) and the resource (durable knowledge), so an agent immediately knows this is the authoring/mutation entry point for the knowledge store. It does not differentiate itself from closest siblings such as manage_knowledge, update_deck, or restore_version, which leaves some ambiguity about scope among the write-family 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?
"Describe its required shape before composing" gives one concrete workflow instruction (pre-flight with describe before authoring), which is genuine usage guidance. However, there is no statement of when to use this tool versus manage_knowledge/commit/restore_version, and no exclusions or prerequisites beyond that single hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a condition needing review or action beyond this session. Current work belongs in topology; platform feedback uses write_feedback.
| Name | Required | Description | Default |
|---|---|---|---|
| refs | No | Optional 1:many rich pointers, e.g. [{kind:'knowledge_record', id:'…'}, {kind:'file', path:'…'}]. | |
| title | No | Scannable one-liner (max 80 chars) — the handle boot renders by; the AI triages on title + severity and reads content only when it works the signal. Omit and it's derived from content (fine for machine-generated signals). Reject-over-cap, never truncated. | |
| action | No | Default 'write'. 'validate': pre-send check — runs the write path's enum + char-cap validation on the candidate WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. State checks (rate cap, dedup, handle resolution) still run at write time. | |
| handle | Yes | Your active deck handle — the agent surfacing the finding | |
| content | Yes | The full finding (max 1000 chars) — fetched via get_signals when the signal is picked up, not shown at boot. Put structured detail in refs, not here. | |
| outcome | No | Required for check signals — pass or fail. | |
| contract | No | Help mode — return the complete contract with no operation performed. | |
| severity | Yes | Your honest estimate — drives how signals are ranked when surfaced at boot. | |
| dedup_key | No | Optional writer-composed key (e.g. 'drift:knowledge:slug-X'). A repeat on an open signal bumps occurrence_count instead of inserting. | |
| assigned_to | No | Optional deck-handle routing label — which deck should pick this signal up (e.g. a specialist raises a finding the container deck fixes, then routes back with assigned_to). Advisory: soft-validated against the container's deck handles, mismatch warns in the envelope, never rejects. Omit for unrouted (container-context surface). | |
| signal_type | Yes | finding: something noticed (default). check: structural assertion (requires outcome). proposition: a suggested action. event: an external thing happened. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read-only, non-destructive write operation. The description adds the useful trait that the signal persists 'beyond this session' and is intended for later review/action, but it does not explain write-time behavior such as dedup, validation, or rate checks; those are left to the parameter 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 sentences with zero filler: the first states the tool's purpose and persistence boundary, and the second handles the two most likely confusable alternatives. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter write tool with no output schema, the description itself is brief, but the input schema is exceptionally detailed and the description covers purpose, persistence, and sibling routing. It is slightly shy of a 5 because return/envelope behavior for the default write path is not mentioned anywhere, though the validate action's return contract is described 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% and each parameter (title cap, content cap, action modes, dedup_key, assigned_to, signal_type, etc.) is already explained in detail in the input schema. 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 opens with a specific verb–object pair: 'Record a condition needing review or action beyond this session,' making it clear the tool persists a signal for later triage. It also distinguishes itself from siblings by explicitly naming write_feedback for platform feedback and topology for current work, so an agent can tell it apart from write_feedback and patch_topology without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-not guidance: current work belongs in topology and platform feedback should use write_feedback. This directly tells the agent to prefer write_signal only for cross-session review/action items and routes other cases to the right sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
read_topology1 field changedInput schema / properties / work_item / descriptionPrevious value: -"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."New value: +"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Takes precedence over trail when both are set."read_topology6 fields changedInput schema / properties / container_id / descriptionPrevious value: -"Container ID — without trail or work_item, returns { projection, state } (see projection). worker_meta is not returned (platform-internal)."New value: +"Container ID — without trail or work_item, returns { projection, state } (see projection), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal)."Input schema / properties / exclude_actionsAdded value: +{
+ "description": "Ops-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
+ "items": {
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 25,
+ "type": "array"
+}Input schema / properties / include_actionsAdded value: +{
+ "description": "Ops-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
+ "items": {
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 25,
+ "type": "array"
+}Input schema / properties / projection / descriptionPrevious value: -"Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first. 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes)."New value: +"Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes)."Input schema / properties / trail / descriptionPrevious value: -"Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?). Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable."New value: +"Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window."Input schema / properties / work_item / descriptionPrevious value: -"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."New value: +"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."patch_topology1 field changedInput schema / properties / op / descriptionPrevious value: -"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): goal/state/next are capped at 250/600/250 chars and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."New value: +"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): what/goal/state/next/blocker are capped at 120/250/600/250/600 chars (a lookup what is never capped) and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."team_work1 field changedInput schema / properties / work / descriptionPrevious value: -"Work item on create_work, or a field patch on update_work/transition_work. goal/state/next are capped at 250/600/250 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."New value: +"Work item on create_work, or a field patch on update_work/transition_work. what/goal/state/next/blocker are capped at 120/250/600/250/600 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."create_pcd_skill1 field changedInput schema / properties / action / descriptionPrevious value: -"Default 'write'. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Uniqueness and deck resolution still run at write time."New value: +"Default 'write'. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Uniqueness, deck resolution and the skill allowance still run at write time (not_checked names them)."diff1 field changedInput schema / properties / version / descriptionPrevious value: -"Version number to compare against. Omit to compare against the latest committed version. For container, names the OLDER snapshot the latest is compared against; omit for latest vs previous."New value: +"Version number to compare against; a deck number resolves to its commit. Omit to compare against the newest saved version (for a deck, possibly a pre-update snapshot). For container, names the OLDER snapshot the latest is compared against; omit for latest vs previous."restore_version2 fields changedInput schema / properties / object_type / descriptionPrevious value: -"Object to restore. console_doc is restricted to platform maintainers. Restore changes working content; commit separately."New value: +"Object to restore. console_doc is restricted to platform maintainers and commits a new version; deck and skill restore working content — commit separately."Input schema / properties / version / descriptionPrevious value: -"Saved version number; supply exactly one of version or version_id."New value: +"Saved version number; a deck number resolves to its commit. Supply exactly one of version or version_id."find_knowledge1 field changedInput schema / properties / category / descriptionPrevious value: -"Filter by category — e.g. 'decision', 'reference', 'manual', 'milestone', 'note'."New value: +"Filter by category — e.g. 'decision', 'reference', 'manual', 'milestone', 'note', 'flow'."read_knowledge5 fields changedInput schema / properties / cross_container / descriptionPrevious value: -"Accept ids from a cross-container browse/search by relaxing the same-container reject; records annotate their container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error."New value: +"Accept ids from a cross-container browse/search by relaxing the same-container reject; records annotate their container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error. Not with stage."Input schema / properties / handleAdded value: +{
+ "description": "Only with stage: your active deck's handle. The stage's skill is read from this deck exactly as run_pcd_skill reads it.",
+ "type": "string"
+}Input schema / properties / projection / descriptionPrevious value: -"Response grain. 'full' (default) returns complete bodies — unchanged behaviour. 'summary' returns metadata + summary only, no raw_markdown — the cheap skim when you already hold ids. 'outline' returns metadata + section_tree (section slugs, headers, per-node hashes, word/paragraph counts — no bodies): the read twin of write_knowledge action='describe'. Lean-then-fetch: outline first, then sections for the parts you need."New value: +"Response grain. 'full' (default) returns complete bodies — unchanged behaviour. 'summary' returns metadata + summary only, no raw_markdown — the cheap skim when you already hold ids. 'outline' returns metadata + section_tree (section slugs, headers, per-node hashes, word/paragraph counts — no bodies): the read twin of write_knowledge action='describe'. Lean-then-fetch: outline first, then sections for the parts you need. Not with stage."Input schema / properties / sections / descriptionPrevious value: -"Section-addressable read — fetch only the named sections instead of the whole body. Requires exactly ONE record_id. Same addressing as the patch surface: a bare level-2 slug returns that section's subtree (intro + level-3 children); a compound 'parent/child' slug returns just that level-3 sub-section. Unknown slugs are rejected with available_sections listed (no silent partial reads). Response items carry { slug, header, level, hash, markdown } + raw_chapter_hash — hashes flow straight into write_knowledge action='patch' expected_hash. Mutually exclusive with projection."New value: +"Section-addressable read — fetch only the named sections instead of the whole body. Requires exactly ONE record_id. Same addressing as the patch surface: a bare level-2 slug returns that section's subtree (intro + level-3 children); a compound 'parent/child' slug returns just that level-3 sub-section. Unknown slugs are rejected with available_sections listed (no silent partial reads). Response items carry { slug, header, level, hash, markdown } + raw_chapter_hash — hashes flow straight into write_knowledge action='patch' expected_hash. Mutually exclusive with projection. Not with stage."Input schema / properties / stageAdded value: +{
+ "description": "Flow stage read: the stage's id or name. Needs exactly one record id — a flow — and handle. Returns the stage as written, its declared routes with their conditions, the flow's Gates, Resumption and Records, and the stage's skill as run_pcd_skill returns it from handle. Not with projection, sections or cross_container.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+}update_deck1 field changedInput schema / properties / content / descriptionPrevious value: -"Partial content patch. Shape: intent (≤600), description (specialized-context only, ≤300 — container-context rejects it; intent is the container's single what-is-this answer), guidelines (instruction_item[]), out_of_bounds (instruction_item[]), data_refs, file_map. file_map is keyed by stable reference name; every item is { path: string, description?: string }, stays deck-local, and key-merges with existing (null deletes a key). instruction_item is { rule, priority, shared? } — per-item shared governs what flows to specialized loads (guidelines/data_refs opt-in via shared:true; out_of_bounds opt-out via shared:false). data_refs entries take optional declaration-layer knobs: read {projection: 'outline'|'summary' | sections: string[]} on medium='kb_record' (grounding grain) and routing 'pcd'|'direct'|'auto' on medium='mcp_connection' (broker vs client reach); rejected on other mediums. Most fields REPLACE on provided — prefer content_ops for single-item edits on the three arrays. session_modes retired — sending it rejects. Optional — may be omitted when only patching name/load."New value: +"Partial content patch. Shape: intent (≤600), description (specialized-context only, ≤300 — container-context rejects it; intent is the container's single what-is-this answer), guidelines (instruction_item[]), out_of_bounds (instruction_item[]), data_refs, file_map. file_map is keyed by stable reference name; every item is { path: string, description?: string }, stays deck-local, and key-merges with existing (null deletes a key). instruction_item is { rule, priority, shared? } — per-item shared governs what flows to specialized loads (guidelines/data_refs opt-in via shared:true; out_of_bounds opt-out via shared:false). data_refs entries take optional declaration-layer knobs: read {projection: 'outline'|'summary' | sections: string[]} on medium='kb_record' (grounding grain) and routing 'pcd'|'direct'|'auto' on medium='mcp_connection' (broker vs client reach); a data_ref of type 'flow' points at a flow record — medium 'kb_record', never mandatory, no read knob, at most 3 per deck; rejected on other mediums. Most fields REPLACE on provided — prefer content_ops for single-item edits on the three arrays. session_modes retired — sending it rejects. Optional — may be omitted when only patching name/load."write_knowledge3 fields changedInput schema / properties / action / descriptionPrevious value: -"Pre-flight, pre-send check, full write, or partial patch. 'describe' returns the category contract + per-record state — no body required. 'validate' runs the exact write-path validation (slug format, status, immutability, template sections, metadata, summary max_length) on a candidate payload WITHOUT writing — returns { valid, missing_required[], over_cap: [{field, len, cap}] }; use it before committing a long compose so an over-cap field costs one cheap check, not a rejected write. Default 'write' commits in one call. 'patch' applies targeted section/paragraph edits to an existing record via `patches[]` without sending the whole body — supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note). On immutable categories (decision, milestone) the patch reconstructs the successor and supersedes (returns action='superseded'); on mutable categories (manual, reference, note) it edits in place (action='patched'). Pre-flight with describe to fetch the current section_tree + hashes."New value: +"Pre-flight, pre-send check, full write, or partial patch. 'describe' returns the category contract + per-record state — no body required. 'validate' runs the exact write-path validation (slug format, status, immutability, template sections, metadata, summary max_length) on a candidate payload WITHOUT writing — for a flow, its stage structure too — returns { valid, missing_required[], over_cap: [{field, len, cap}] }; use it before committing a long compose so an over-cap field costs one cheap check, not a rejected write. Default 'write' commits in one call. 'patch' applies targeted section/paragraph edits to an existing record via `patches[]` without sending the whole body — supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) the patch reconstructs the successor and supersedes (returns action='superseded'); on mutable categories (manual, reference, note, flow) it edits in place (action='patched'); on a flow the stages are re-checked on the patched body first. Pre-flight with describe to fetch the current section_tree + hashes."Input schema / properties / category / descriptionPrevious value: -"Category — must be declared in the manifest (note, decision, reference, manual, milestone). 'knowledge' is reserved. Immutability + locking are derived from the manifest's transitions on promotion."New value: +"Category — must be declared in the manifest (note, decision, reference, manual, milestone, flow). 'knowledge' is reserved. Immutability + locking are derived from the manifest's transitions on promotion. A record never moves into or out of 'flow' — write a new record instead."Input schema / properties / patches / descriptionPrevious value: -"Array of patch ops for action='patch'. Level-2 ops: replace_section / replace_section_intro / append_section / insert_section_after / remove_section. Level-3 ops: replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Both levels: rename_section — { section_slug, new_header, expected_hash? } renames a heading + its slug without resending the body; body and children untouched, child slugs cascade on a level-2 rename; required frame sections reject (REQUIRED_SECTION), slug collisions reject (DUPLICATE_HEADER). Section slugs are doc-local addressing, not a stable cross-doc contract — a rename that changes a slug raises a repair signal for cross-record references (warning in the response). Addressing: level-2 ops take section_slug=<bare slug> (insert_section_after takes after_section_slug). Level-3 ops take section_slug=<parent's BARE slug> PLUS the child's compound 'parent/child' slug in paragraph_slug (after_paragraph_slug for insert_paragraph_after) — never put the compound slug in section_slug (exception: rename_section on a level-3 child takes the compound slug directly in section_slug); append_paragraph / prepend_paragraph create a new child under section_slug=<parent> with the title in header. See section_tree.addressing in the describe response. Each op also carries content/header as applicable. content is BODY-ONLY: never include the section's '## …'/'### …' heading line — the heading is emitted from the slug (replace ops) or the header param (append/insert ops); a content opening with a heading line is rejected with HEADER_IN_CONTENT. Ops without a header param reject a stray header field (UNEXPECTED_HEADER) — renaming goes through rename_section, never a header on replace_section. replace_section_intro edits ONLY a level-2 section's own lead text and preserves its level-3 children — use it to fix a parent section's intro when it has subsections (replace_section refuses such a section with CHILDREN_PRESENT). replace_section / replace_section_intro / replace_paragraph / remove_paragraph / rename_section accept optional expected_hash for optimistic concurrency. Pass as JSON array; the worker also accepts a JSON-encoded string. Supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note). On immutable categories (decision, milestone) a patch reconstructs the successor and supersedes rather than editing in place."New value: +"Array of patch ops for action='patch'. Level-2 ops: replace_section / replace_section_intro / append_section / insert_section_after / remove_section. Level-3 ops: replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Both levels: rename_section — { section_slug, new_header, expected_hash? } renames a heading + its slug without resending the body; body and children untouched, child slugs cascade on a level-2 rename; required frame sections reject (REQUIRED_SECTION), slug collisions reject (DUPLICATE_HEADER). Section slugs are doc-local addressing, not a stable cross-doc contract — a rename that changes a slug raises a repair signal for cross-record references (warning in the response). Addressing: level-2 ops take section_slug=<bare slug> (insert_section_after takes after_section_slug). Level-3 ops take section_slug=<parent's BARE slug> PLUS the child's compound 'parent/child' slug in paragraph_slug (after_paragraph_slug for insert_paragraph_after) — never put the compound slug in section_slug (exception: rename_section on a level-3 child takes the compound slug directly in section_slug); append_paragraph / prepend_paragraph create a new child under section_slug=<parent> with the title in header. See section_tree.addressing in the describe response. Each op also carries content/header as applicable. content is BODY-ONLY: never include the section's '## …'/'### …' heading line — the heading is emitted from the slug (replace ops) or the header param (append/insert ops); a content opening with a heading line is rejected with HEADER_IN_CONTENT. Ops without a header param reject a stray header field (UNEXPECTED_HEADER) — renaming goes through rename_section, never a header on replace_section. replace_section_intro edits ONLY a level-2 section's own lead text and preserves its level-3 children — use it to fix a parent section's intro when it has subsections (replace_section refuses such a section with CHILDREN_PRESENT). replace_section / replace_section_intro / replace_paragraph / remove_paragraph / rename_section accept optional expected_hash for optimistic concurrency. Pass as JSON array; the worker also accepts a JSON-encoded string. Supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) a patch reconstructs the successor and supersedes rather than editing in place."team_work12 fields changedInput schema / properties / work / descriptionPrevious value: -"Work item on create_work, or a field patch on update_work/transition_work. Provenance is server-stamped."New value: +"Work item on create_work, or a field patch on update_work/transition_work. goal/state/next are capped at 250/600/250 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."Input schema / properties / work / properties / blocker / maxLengthRemoved value: -1000Input schema / properties / work / properties / blocker / minLengthRemoved value: -1Input schema / properties / work / properties / goal / maxLengthRemoved value: -1000Input schema / properties / work / properties / goal / minLengthRemoved value: -1Input schema / properties / work / properties / next / maxLengthRemoved value: -1000Input schema / properties / work / properties / next / minLengthRemoved value: -1Input schema / properties / work / properties / refsAdded value: +{
+ "description": "Typed pointers {kind, label?, locator}; sending refs replaces the stored array. See describe.work_item_shape.",
+ "items": {},
+ "type": "array"
+}Input schema / properties / work / properties / state / maxLengthRemoved value: -2000Input schema / properties / work / properties / state / minLengthRemoved value: -1Input schema / properties / work / properties / what / maxLengthRemoved value: -200Input schema / properties / work / properties / what / minLengthRemoved value: -1patch_topology2 fields changedInput schema / properties / op / descriptionPrevious value: -"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source)."New value: +"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): goal/state/next are capped at 250/600/250 chars and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."Input schema / properties / payload / descriptionPrevious value: -"Required when action='patch' or 'validate' (validate takes the same candidate payload the patch would send). Ignored when action='describe'. Op-specific payload. work_patch: {what, patch: {goal?, state?, next?, assigned_to?, refs_append?: [...]}} — partial merge on the item matched by `what` (any group); provided fields update, untouched fields survive; refs_append appends to refs[] (exact duplicates skipped with a warning); empty or unknown-field patches are rejected with the patchable field list (`detail` rejects — renamed to `state`). Stamps item.updated (the freshness clock behind the boot hygiene flags). assigned_to soft-validates like work_upsert. work_upsert: {group: 'active'|'paused'|'blocked'|'done', item: {what, goal?, state?, next?, refs?, annotations?, assigned_to?, ...}} — `detail` is rejected (renamed to `state`, topology 3.0); blocked requires `blocker`; done auto-stamps `closed` if missing; item.updated stamps on every upsert. Caps: active/paused 5, blocked 3, done 5 — over-cap on active/paused/blocked is REJECTED with a make-room hint (work items are never silently evicted); done alone trims oldest-by-closed. assigned_to is an advisory deck handle: soft-validated against the container's decks, mismatch warns in the envelope, never rejects. work_transition: {what, to: 'active'|'paused'|'blocked'|'done', patch?: {...}} — transitioning to blocked requires `blocker` in patch; moving into a full active/paused/blocked group is REJECTED (make room first — the source item stays put), done trims oldest-by-closed. work_remove: {what}. work_annotate: {what, type, text: string|string[], actor?} — `what` matches the work item's `what` field (the same item key as work_patch/work_transition/work_remove); `type` is open vocabulary (gotchas, choice, observation, shipped, attempt, risk, …); `text` is the annotation content, aligned with did_append. Char caps (150 chars/bullet, 900 total) are REJECTED over-cap with a field+limit message (never truncated) — tighten and resend; the 6-bullet cap drops oldest. Per-item cap 10: an over-cap append succeeds and RETURNS the evicted annotation in evicted_annotations (annotations are memory, never silently destroyed) — graduate it to knowledge or fold it into the item if it still matters. did_append: {text, work_ref?, by?} — record a COMPLETION into the did trail (topology 3.0): `text` ≤250 chars (rejected over-cap); optional `work_ref` (a work item's `what` this completion closes) and `by` (your deck handle). Append-only, retention keep-everything; boot ships a tail of 8, read_topology pages deeper (trail='did'). A work_ref still in active/paused returns a nudge. Use for finished things — in-flight standing stays on the work item's `state` via work_patch."New value: +"Required when action='patch' or 'validate' (validate takes the same candidate payload the patch would send). Ignored when action='describe'. Op-specific payload. work_patch: {what, patch: {goal?, state?, next?, assigned_to?, refs_append?: [...]}} — partial merge on the item matched by `what` (any group); provided fields update, untouched fields survive; refs_append appends to refs[] (exact duplicates skipped with a warning); empty or unknown-field patches are rejected with the patchable field list (`detail` rejects — renamed to `state`). `state` REPLACES — write the new standing from scratch, never the old text plus a layer; goal/state/next reject over 250/600/250 chars. Each appended ref is {kind, label?, locator}: kinds are knowledge | skill | signal | connection | url | file, the locator is the one its kind needs, and nothing else is accepted; the merged refs[] caps at 8. Stamps item.updated (the freshness clock behind the boot hygiene flags). assigned_to soft-validates like work_upsert. work_upsert: {group: 'active'|'paused'|'blocked'|'done', item: {what, goal?, state?, next?, refs?: [{kind, label?, <locator>}], annotations?, assigned_to?, ...}} — `detail` is rejected (renamed to `state`, topology 3.0); blocked requires `blocker`; done auto-stamps `closed` if missing; item.updated stamps on every upsert. Caps: active/paused 5, blocked 3, done 5 — over-cap on active/paused/blocked is REJECTED with a make-room hint (work items are never silently evicted); done alone trims oldest-by-closed. assigned_to is an advisory deck handle: soft-validated against the container's decks, mismatch warns in the envelope, never rejects. The sent item is checked against the work-item caps and ref shape; knowledge/skill/signal refs must resolve in this container, and a connection ref naming nothing the container declared warns and lands. work_transition: {what, to: 'active'|'paused'|'blocked'|'done', patch?: {...}} — transitioning to blocked requires `blocker` in patch; moving into a full active/paused/blocked group is REJECTED (make room first — the source item stays put), done trims oldest-by-closed. Only the patch you send is checked against the caps and ref shape — the stored item's other fields are left alone, so a bare transition of a legacy over-shape item passes. work_remove: {what}. work_annotate: {what, type, text: string|string[], actor?} — `what` matches the work item's `what` field (the same item key as work_patch/work_transition/work_remove); `type` is open vocabulary (gotchas, choice, observation, shipped, attempt, risk, …); `text` is the annotation content, aligned with did_append. Char caps (150 chars/bullet, 900 total) are REJECTED over-cap with a field+limit message (never truncated) — tighten and resend; the 6-bullet cap drops oldest. Per-item cap 10: an over-cap append succeeds and RETURNS the evicted annotation in evicted_annotations (annotations are memory, never silently destroyed) — graduate it to knowledge or fold it into the item if it still matters. did_append: {text, work_ref?, by?} — record a COMPLETION into the did trail (topology 3.0): `text` ≤250 chars (rejected over-cap); optional `work_ref` (a work item's `what` this completion closes) and `by` (your deck handle). Append-only, retention keep-everything; boot ships a tail of 8, read_topology pages deeper (trail='did'). A work_ref still in active/paused returns a nudge. Use for finished things — in-flight standing stays on the work item's `state` via work_patch."team_work6 fields changedInput schema / properties / action / descriptionPrevious value: -"Operation. Call describe before composing an unfamiliar contribution or work write."New value: +"Operation. Call describe before composing an unfamiliar contribution, work write, or document action; describe.document_actions is the action-specific contract."Input schema / properties / expected_revision / descriptionPrevious value: -"Current proposal revision required for revise_contribution and mark_ready."New value: +"Current immutable record revision required for revise_contribution, mark_ready, revise_document, and submit_document."Input schema / properties / expected_transition_revision / descriptionPrevious value: -"Current transition revision required for revise_contribution and mark_ready."New value: +"Current lifecycle transition revision required by contribution and document writes; open_document_round accepts this version but not expected_revision."Input schema / properties / limit / descriptionPrevious value: -"Maximum review requests returned; defaults to 20."New value: +"Result cap: read_reviews and list_documents default to 20 with maximum 50; search_documents defaults to 10 with maximum 20."Input schema / properties / record_id / descriptionPrevious value: -"Versioned team contribution record for reads, revision, or readiness."New value: +"Versioned Team record. Required by record- and document-specific reads and writes; inspect describe.document_actions for each document action."Input schema / properties / revision / descriptionAdded value: +"Immutable document revision to check with check_document; defaults to the current revision. It is not an optimistic write token."
Add one secure layer between your agents and this server.