PCD (Portable Context Deck)

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.

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.

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.

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.

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.

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.

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

Annotations already establish that the tool is not read-only and not destructive, so the description does not need to restate that. The prose adds persistence-oriented framing ('preserved for future use') but does not surface the validate mode's no-write behavior, the contract help mode, or signal-emission semantics; those are left to the parameter schema. 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?

Two sentences, no filler: the first front-loads the purpose and the second handles the sibling distinction. Every clause earns its place.

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

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

With nine parameters and several nested objects, this is a complex tool, but the schema descriptions are exhaustive and the annotations cover the safety profile. The remaining gap is that the prose does not summarize the special write/validate/contract modes or return behavior, which an agent only discovers by reading the parameter schema in full.

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

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

Schema description coverage is 100%, so the structured schema carries the meaning of all nine parameters and nested objects. The prose adds no parameter-specific detail beyond the 'preserved method' framing, which maps loosely to raw_markdown/description but does not materially improve semantic understanding.

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

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

The description opens with a specific action and object — 'Create a reusable working method' — and ties it to a concrete user intent: 'when the user wants a procedure preserved for future use.' It also distinguishes itself from the closest sibling by adding 'Use update_pcd_skill to revise an existing method,' so an agent can tell creation from revision at a glance.

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

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

It gives an explicit trigger condition for using this tool ('when the user wants a procedure preserved for future use') and an explicit alternative for the overlapping case ('Use update_pcd_skill to revise an existing method'). This is sufficient routing guidance 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.

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

The readOnlyHint annotation already establishes that the tool does not mutate state, and the description adds no contradictory information. However, the description does not elaborate on any additional side effects or behavioral nuances beyond 'compare', so it provides only baseline transparency beyond the annotation.

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 conveys the tool's function without unnecessary wording. It is front-loaded with the core action and resource, making it easy to parse quickly.

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

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

Given the lack of an output schema, the description adequately explains what the tool does. It does not detail the exact format of the diff result, but this is not strictly required. The context from sibling tools and the object_type enum provides sufficient orientation for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and each parameter description adds meaningful semantic detail beyond the schema. For example, the 'version' parameter explains the default behavior when omitted and the special meaning for containers, and 'object_id' clarifies when it is required versus optional.

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 verb 'compare' and the resource 'supported objects' with 'saved versions'. The object_type enum further specifies which object types are supported (deck, console_doc, container, skill), leaving no ambiguity about the tool's purpose.

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

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

The description does not explicitly indicate when to use this tool over alternatives like commit or restore_version. It lacks guidance on scenarios where a diff is appropriate or when another sibling tool would be more suitable, leaving the agent to infer usage context.

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

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

The readOnlyHint annotation is consistent with the description, and the description adds important behavioral details such as default draft exclusion, cursor-paginated listing, query/cursor exclusivity, and the cross_container gate restriction. It does not contradict the annotation and gives a solid picture of side-effect-free behavior.

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

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

The description is compact and front-loaded with the primary purpose, while parameter details are structured and scannable. Every sentence adds relevant information without redundancy or 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 explains the return concept (candidate summaries and IDs) and pagination cursor, which is essential since there is no output schema. It could be more explicit about the exact response shape or error behavior, but the provided details are sufficient for an agent to invoke the tool and interpret results 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?

All 12 parameters are documented with meaningful semantic detail, including defaults, constraints, and conditional behaviors like query rejecting cursor and include_drafts interacting with status. The schema description coverage is 100%, and parameter descriptions go beyond basic type info to clarify filter semantics and edge cases.

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 finds knowledge records by topic or filters, and explicitly distinguishes it from read_knowledge by noting it returns candidate summaries and IDs for later evidence retrieval. The verb 'find' and resource 'knowledge records' are specific and 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 provides contextual use cases ('when answering a question or locating a reference') and points to read_knowledge for evidence, which helps select among siblings. It does not exhaustively contrast with write_knowledge or manage_knowledge, but the read-only annotation and the candidate/evidence split give sufficient guidance for typical use.

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

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

The 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.

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.

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.

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.

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.

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

The tool definition's op descriptions expose destructive behavior: work_remove deletes an item from any group, done trims oldest-by-closed, and annotation over-cap evicts entries. This contradicts the annotation destructiveHint=false, and the top-level description adds no reconciling context. An agent relying on the annotation could be misled about the tool's safety profile.

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 two sentences are tight, front-loaded with purpose, and include a useful pre-flight tip with no filler. It is concise, though the tool's complexity means most of the burden falls on 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?

For a five-parameter tool with nested payloads, multiple action/op modes, and no output schema, the top-level description is too thin on its own: it does not mention the describe/validate/patch actions, op distinctions, or return expectations. The rich schema compensates for input coverage, but not fully for selection-level and side-effect 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 description coverage is 100%, and the schema already documents every parameter in depth, including op-specific payloads and caps. The top-level description contributes no additional 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?

The description names a concrete action set — updating work, annotations, and recording completions — and clearly positions this as a mutation tool alongside the title. It is specific enough to distinguish from read-oriented siblings like read_topology, though it does not explicitly differentiate it from the many other write/update 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 gives a real pre-flight heuristic: call describe before composing unfamiliar operations. However, it never states when to prefer patch_topology over a sibling write tool, when not to use it, or which action/op combinations are appropriate for which situations; those details are left to the schema.

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

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

With 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.

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.

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

The readOnlyHint annotation is consistent with the read-only nature of the tool. The description adds useful behavioral detail beyond the annotation, such as rejecting unknown slugs with available_sections, mutual exclusions, and the 'no silent partial reads' guarantee.

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 top-level description is concise, and the detailed parameter descriptions are well organized. The overall length is justified by the complexity of aliases, projections, and section addressing, though it could be tightened slightly.

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

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

There is no output schema, but the description conveys key response characteristics: response item fields for sections, hash propagation, summary/outline content differences, and error behavior. It does not fully describe the top-level response envelope, but it is enough for an agent to understand the main outcomes.

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?

Although schema coverage is 100%, the description adds substantial meaning: alias resolution, record_ids winning over ids, exactly-one-record requirement for sections, section addressing rules, projection grains, and cross-container restrictions. 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 description uses a specific verb ('Retrieve') with a clear resource ('knowledge bodies, outlines or selected sections') and a clear input ('by record ID'). It distinguishes the read operation from sibling write/search tools like write_knowledge and 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?

The description provides strong usage guidance through projection semantics, 'lean-then-fetch', and references to find_knowledge and write_knowledge. It does not explicitly say 'use this instead of X', but the retrieval verb and parameter references make the intended context clear.

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

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

The 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.

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

The description consistently reflects the read-only annotation by describing operations as returning data and explicitly stating that help mode performs no operation. It also discloses edge behavior like errors when no work item exists and ignored parameters, providing good transparency without contradicting the readOnlyHint.

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

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

The description is dense but each sentence carries functional value, covering modes, paging, projections, and error conditions without irrelevant filler. While lengthy, the structure groups related parameters and keeps the information organized, making it efficient for an agent to parse.

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

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

Although there is no output schema, the description provides return shapes for each mode, mentions defaults and paging behavior, and notes error cases. This gives an agent enough context to understand what to expect and how to use the tool correctly, though exact field details of the returned state are not fully specified.

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 seven parameters are described in the schema, and the description adds meaningful behavior beyond the raw schema, such as defaults, mutual exclusivity, and the purpose of work_item for reviving paused threads. It does not simply restate the schema; it explains when each parameter matters.

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 the tool's purpose with a specific verb ('Read') and clearly distinguishes the three resource types it can read: current work, a particular work item, or historical trails. This makes the tool's scope immediately understandable and differentiates it from sibling tools that write or manage topology.

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 practical guidance for when to use each mode, such as using work_item to revive a paused thread when boot trim hid context, and explains mutual exclusions and ignored parameters. It does not explicitly compare against sibling tools, but the mode-specific instructions are sufficient for typical selection.

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

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

The 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.

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.

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Beyond that, the description and schema add useful context: console_doc restores are restricted to platform maintainers, and restoring 'changes working content' which must be committed separately. This enriches the annotation with operational detail and does not contradict it.

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

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

The description is a single concise sentence that front-loads the core action and resource, then appends the important maintainer restriction. No filler or redundant wording 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 combination of the description, the rich 100%-covered schema, and the annotations gives an agent enough to invoke the tool correctly. The main gap is the lack of higher-level guidance about when to restore versus using related tools like diff or load_deck, and no mention of the response, but these are secondary given the schema's completeness.

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

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

Schema description coverage is 100%, so the input schema already documents all six parameters. The tool description does not add deeper meaning about the parameters or their relationships, 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 action ('Restore') on specific resource kinds ('deck', 'skill', and for maintainers 'console documents') from a saved version. It is clear and unambiguous, though it does not explicitly differentiate itself from sibling tools like load_deck or update_deck.

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 instead of alternatives such as diff, load_deck, update_deck, or commit. The schema notes 'commit separately,' but the description itself gives no context about workflow steps or when restoration is appropriate.

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

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

The description 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.

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.

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.

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

The description adds 'permission-checked' and 'versioned' context, which are useful behavioral traits. Annotations already indicate non-readonly and non-destructive, so no contradiction. However, it does not disclose the tool's complexity (26 actions), the need to call describe first, or any rate limits – the schema partially covers describe, but the description itself is sparse.

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, efficient sentence that front-loads the core capabilities without fluff. It is concise but omits mention of document actions and the describe entry point, so it is slightly under-informative for such a large 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?

With 26 actions, 36 parameters, no output schema, and only 58% schema coverage, the description is far too thin. It does not hint at document workflows, feedback, or the describe-before-use contract, leaving an agent to discover these through the schema or trial. Significant gaps remain.

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 58%, and many parameters have inline descriptions (e.g., action, limit, work_id, expected_revision). The tool description does not add parameter meaning beyond what the schema provides. Baseline 3 is appropriate since the schema carries most of the 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?

The description uses specific verbs (read, advance, publish, request/respond) and identifies the resource (shared work, versioned contributions, exact-version reviews). It distinguishes the tool as a 'team destination' but does not name sibling alternatives or enumerate the full action set, so it is clear but not exhaustive.

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 implies usage for team-related work/contribution/review operations but gives no explicit when-to-use vs. alternatives. There are no exclusions or conditions. Given the broad scope and many sibling tools, some routing guidance would help.

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

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

It clearly explains write semantics: fields replace, content_ops apply sequentially with no partial application, session_modes is rejected, and 'validate' performs no write. It does not mention permissions or rate limits, but the core behavioral effects are well disclosed.

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

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

The description is long but mostly dense with necessary operational detail. Some repetition exists, such as 'Mirrored onto raw_json...' appearing for multiple fields, but each sentence generally contributes to understanding the tool's behavior.

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

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

The input semantics are thoroughly covered, including the validate return shape and contract help mode. However, there is no output schema and no description of the normal successful write response, which leaves some uncertainty about what the agent should expect after a standard update.

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 a detailed, purpose-specific description covering constraints, alternatives, optionality, and interactions. The descriptions go well beyond the schema types and enums, especially for content, content_ops, and identifier selection.

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 action — 'Revise a container or specialist deck configuration' — with a specific resource type. This distinguishes it from related tools like create_deck, read_deck, and switch_deck.

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 some usage guidance, such as preferring content_ops for single-item edits, excluding platform-managed deck types, and using 'validate' for pre-send checks. However, it does not explicitly contrast when to use update_deck versus create_deck, load_deck, or switch_deck.

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

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

Annotations already 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.

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.

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.

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.

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.

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

The description clearly discloses side effects and non-effects: 'validate' runs checks WITHOUT writing, 'describe' returns the contract with no body required, patch either edits in place or reconstructs the successor and supersedes, and promotion to a live_state fires on_promote side-effects. It also warns about repair signals, optimistic concurrency rejections, and atomic supersession behavior, going well beyond the minimal 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 extremely long and contains clear duplication: the 'Supported on any category whose template declares a section_schema...' sentence appears nearly verbatim in both the action and patches fields. While much of the detail is necessary for a complex patch API, the redundancy and overall verbosity prevent it from being appropriately sized.

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

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

The description is remarkably complete for a tool with no output schema. It documents return shapes for validate and describe, patch action outcomes ('patched' vs 'superseded'), common error conditions (REQUIRED_SECTION, DUPLICATE_HEADER, HEADER_IN_CONTENT, UNEXPECTED_HEADER, CHILDREN_PRESENT), and the role of hashes in concurrency. It leaves little ambiguity about how the tool behaves across the supported scenarios.

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?

Even though schema coverage is 100%, the description adds substantial semantic detail: the action enum's behavioral differences, patch op addressing rules, the distinction between section_slug and paragraph_slug, BODY-ONLY content with HEADER_IN_CONTENT rejection, expected_hash usage, and the supersede vs superseded_by difference. This transforms enumerations and generic fields into actionable guidance.

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, specific statement of the tool's purpose — 'Create, revise, patch or supersede durable knowledge' — and immediately orients the agent toward the 'describe before composing' workflow. It is easily distinguished from read/find knowledge tools and covers all core action modes.

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 strong, explicit usage guidance: when to use 'describe' for pre-flight, when to use 'validate' before a long compose, when to use 'patch' vs full 'write', and when to use 'supersede: true' ('Use this on a decision rewrite, not on a routine update'). It also states which categories support patching and how immutable categories behave.

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

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

Annotations already 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.