TeamShared

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

With no annotations provided, the description carries full burden. It discloses behavioral traits: 'The append self-heals expired sessions', 'the response's session_id is authoritative', and specifies the return shape. This provides useful behavioral context beyond the input 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 extremely concise at three sentences, each earning its place: the first summarizes the tool's purpose, the second contrasts with alternatives, the third adds behavioral nuance and return shape. No wasted words.

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?

Despite 7 parameters, the combination of the description's behavioral disclosure and the 100% schema-covered input schema makes this complete. The description references the output shape which is documented in the output schema, and the complex coordinator behavior is adequately summarized.

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 baseline is 3. The description adds value by explaining how parameters relate (e.g., summary appends to the session, close triggers queued distillation, facts are durable memories). This semantic grouping and operational context elevates it above the baseline.

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

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

The description clearly states it is a 'Turn-end batch' tool that handles assistant summary, durable writes, and optional session close. It explicitly contrasts with the multi-call sequence it replaces (memory_session_append + memory_remember + memory_session_close + memory_state_set), distinguishing it from all 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?

The description explicitly states 'One call replaces the end-of-turn memory_session_append + memory_remember (+ memory_session_close + memory_state_set) sequence', giving clear context for when to use this tool instead of alternatives. However, it does not explicitly mention situations where it should NOT be used.

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

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

With no annotations provided, the description fully discloses behavioral traits: compression algorithm (SmartCrusher-lite), storage of originals in Redis with reference markers, and the fact that the tool always executes. It does not mention auth requirements or rate limits, but for a non-destructive compression tool the description is sufficiently transparent.

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

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

The description is two efficient sentences plus a short tuning note. It front-loads the core purpose, then provides key details (method, storage, always-run behavior, configurability) without wasted words. Every sentence adds 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?

Given a single parameter with full schema coverage and an output schema (which relieves the description from explaining return values), the description adequately covers what the tool does, how it works, storage behavior, and configuration. It could mention ordering relative to other context tools or handling of empty inputs, but overall it is mostly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description adds context about the types of content shrunk (tool outputs, logs, long text) and the storage mechanism, which complements the schema's description of message preservation. However, the description does not add structural or formatting details beyond the schema for the single parameter.

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 compresses prompt payloads before LLM processing, specifying it shrinks JSON tool outputs, logs, and long text. It mentions a complementary sibling (context_retrieve) but does not explicitly differentiate from other context tools like context_normalize or context_prepare, so sibling distinction is partial but purpose is specific.

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 notes the tool 'always runs,' implying automatic invocation, and mentions tunable thresholds via environment variables. It lacks explicit when-to-use or when-not-to-use guidance and does not compare with alternatives like context_normalize or context_prepare. Usage context 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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: trimming recall-style payloads, shrinking large JSON/logs, storing originals in CCR when compressed. This is thorough for a transformation tool.

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

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

The description is two sentences, no fluff, but could be slightly restructured so the action verb comes first. It is still concise and front-loaded with the purpose.

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

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

Given the simplicity (2 parameters, full schema coverage, output schema present), the description covers the essential use cases and boundaries. It could be more specific about what 'large JSON/logs' means, but it is complete enough for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add specific details about the parameters beyond what the schema provides (e.g., what qualifies as 'raw' or 'usually JSON'), but that is acceptable given 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 verb (strip, clean, compress), the resource (non-teamshared tool output), and the purpose (prepare for agent context). It also notes it stores originals in CCR, differentiating it from other context 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 explicitly tells when to use this tool (for Shell, Grep, or other harness tools) and when not to use it (prefer MCP middleware for teamshared tools). It does not mention specific alternatives among siblings, but the guidance is clear enough.

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

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

No annotations are provided, so the description carries the full burden. It explains the pipeline steps and output fields (compressed messages, additional_context, session_id, stats). However, it does not disclose whether the tool mutates state (e.g., the session) or any required permissions/rate limits. The description is adequate but lacks full transparency on side effects.

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 paragraph of 4 sentences, front-loaded with the pipeline steps. It is concise and each sentence adds value. However, it could be better structured with bullet points or clearer separation of purpose, usage, and outputs for easier parsing by an agent.

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

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

Given the 8 parameters and no output schema in the provided context, the description covers the key aspects: pipeline stages, output fields, and usage context. It explains how this tool fits within the broader system (server-side middleware handling teamshared tool responses). However, it lacks details on what 'compress' or 'enrich' entail precisely, which could be helpful for fine-grained decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema – it mentions 'additional_context (org memory)' which hints at the 'enrich' parameter's function, but overall does not significantly enhance understanding of parameter semantics.

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

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

The description states it is a 'Pre-LLM pipeline' with specific steps: session append, compress, enrich. It clearly identifies the verb (pipeline preparation), resource (incoming history, session, context), and distinguishes itself from sibling tools like context_compress or context_retrieve by being a combined pipeline meant for pre-LLM use.

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 'Use before sending a turn to your LLM when you want teamshared to shrink tool bloat and inject recall.' This provides clear context for when to use. However, it does not explicitly mention when not to use it or name alternative tools for specific sub-tasks, though the sibling set implies alternatives exist.

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

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

No annotations are provided, so the description carries full burden. It states the tool retrieves original content from a compressed block, implying a read operation. However, it does not disclose any potential side effects, permissions needed, rate limits, or what happens if the ref is invalid. The description is honest but minimally transparent beyond the core action.

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 that clearly conveys the tool's purpose. Every word is functional, with no wasted text. It is appropriately sized for a simple 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?

Given the tool has only one parameter (covered by schema), no annotations, but an output schema exists (not shown here), the description adequately explains the input and action. The output schema likely handles return value documentation. Contextual completeness is high for a focused retrieval tool.

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

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

Schema description coverage is 100%, with one parameter 'ref' described as 'CCR ref from a compressed message (ref=ccr_...)'. The description adds slight value by stating the ref comes from a 'compressed block', but this mostly restates the schema. Baseline 3 is appropriate as the schema already covers the parameter well.

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 indicates the verb 'Retrieve' and the resource 'original content for a compressed block via CCR ref'. It distinguishes from siblings like context_compress and context_commit, which have different purposes (compression and committing). However, the term 'compressed block' could be slightly ambiguous without context, but overall it's specific.

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

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

The description implies when to use this tool—when you have a CCR ref from a compressed message and need to retrieve the original—but it does not explicitly state when not to use it or provide alternative tools. The sibling list includes many memory and context tools, but no guidance on alternatives, making it an implied usage case.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the file is retained with version history for audit, and that the public share route returns 404. It doesn't mention required permissions or if the operation is reversible, but the behavioral effects are well documented.

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 concise, using two well-structured paragraphs. The first sentence gives the core action and secondary effect, and the second adds critical behavioral details (version history retention, 404 for shared route). No wasted words.

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

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

Given the tool's simplicity (1 parameter, clear schema, output schema present), the description adequately covers the purpose and behavioral effects. It doesn't explain the output schema's contents, but that is handled by the schema itself. Slightly more could be said about reversibility or permissions, but overall it's complete for this complexity level.

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

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

Schema description coverage is 100% and there is only one parameter (file_id) with a clear 'File UUID to archive' description. The tool description does not add further parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Archive a shared file'), the resource ('shared file'), and the dual effect: exclusion from active lists and cleanup of its bucket mirror. This distinguishes it well from file operations like file_delete, file_unpublish, or file_get, and from other 'archive' tools like project_archive.

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 archiving a shared file, and clarifies what archiving means (excluded from active lists, bucket mirror cleanup). It does not explicitly say when not to use it or name alternatives, but given the sibling list, the context is clear that this is for archiving, not deleting or unpublishing.

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

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

No annotations exist, so the description carries the full burden. It discloses that files default to private and that file_update creates immutable versions. It does not mention authentication requirements, rate limits, or side effects. The behavioral information is present but not exhaustive.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence adds value: creation, default privacy, publish workflow, versioning behavior. No wasted words.

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 presence of an output schema (not shown but indicated), the description does not need to explain return values. It covers creation behavior, privacy defaults, and links to related tools. It could be more complete about the initial state (e.g., file location, owner), but overall it is sufficient for a creation tool.

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

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

Schema coverage is 100% (baseline 3). The description adds no parameter-specific meaning beyond the schema. It mentions 'versioned shared file' and 'private default' but does not elaborate on fields like title, content, or content_format 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 states 'Create a new versioned shared file' with a specific verb and resource. It distinguishes from siblings like 'file_update' (creates new versions) and 'file_publish' (generates share URL), making the tool's unique role clear.

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

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

The description gives a workflow hint: default private, then call file_publish for public URL. It also mentions that file_update creates new versions, implying file_create is for initial creation. However, it does not explicitly compare to other file creation tools like file_upload_request or state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool fetches the 'latest version content' and includes 'public_url' when published, which are useful but sparse. It does not disclose whether the tool is read-only (likely safe), what happens if the file is unpublished, whether it errors on invalid IDs, or rate limits. The description adds reasonable context but misses opportunities for deeper 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 extremely concise: two sentences that are front-loaded with the main action ('Fetch a shared file with its latest version content'). The second sentence adds a specific detail about the public URL without extra fluff. Every sentence earns its place, and there is no redundant or vague wording. This is a model of conciseness.

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

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

Given the tool's low complexity (1 parameter, read-like operation) and the presence of an output schema, the description is nearly complete. It covers enough for an agent to understand the core function and a key return detail (public URL). However, it would be slightly stronger if it hinted at error conditions (e.g., file not found or access denied) or confirmed that no side effects occur. For a simple tool, this is well above minimal viability.

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 has one parameter (file_id) with 100% description coverage (described as 'File UUID'). The description does not add additional semantic meaning beyond the schema for the parameter itself. The description's mention of 'latest version content' and 'public_url' provides context for the return value, not the parameter. With full schema coverage, the baseline is 3, and the description does not exceed this by adding parameter-specific details.

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 fetches a shared file with its latest version content, using the specific verb 'Fetch' and resource 'shared file'. It also adds value by mentioning the inclusion of 'public_url' when the file is published, distinguishing this from other file operations like file_list (listing files) or file_create (creating files). Among siblings like file_archive, file_publish, or file_update, this tool's purpose is distinct and well-defined.

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

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

The description implies usage for retrieving a specific file by its ID, and the single required parameter (file_id) reinforces this. However, there is no explicit guidance on when to use this tool versus alternatives like file_list (to find files) or file_version_delete (to manage versions). It doesn't state prerequisites (e.g., file must exist or user needs access) nor exclusions (e.g., cannot fetch without ID).

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

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

No annotations provided, so description carries full burden. Describes returned fields (public_url, slug, share_token) and query behavior, but does not mention pagination, rate limits, or effect on file state. Acceptable but could detail more edge cases.

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

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

Three compact sentences, front-loaded with core behavior, then details on returned fields and a concrete example. No fluff or repetition.

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

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

For a listing tool with 2 optional parameters and output schema, the description covers key behavioral aspects (ordering, scope, query usage, relevant fields). Could mention pagination or max results implied by limit, but not critical given simplicity.

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 50% with 2 parameters; description adds value by illustrating query usage with an example ('yield vault'), which clarifies substring matching. However, limit parameter semantics are not enhanced beyond schema. Baseline 3 is appropriate.

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

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

Clearly states it lists active shared files, ordered by newest update, and scoped to the caller's org. Distinguishes from file_get (single file) and file_archive (archive action) among siblings, but could be more explicit about what 'active' excludes.

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

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

Provides example use of query parameter to avoid listing everything, but does not discuss when to use alternatives like file_search (not present) or when not to use this tool (e.g., for retrieving deleted files). Could benefit from excluding cases.

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

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

With no annotations, the description carries the full burden. It discloses idempotency, eager HTML push, and URL format. It does not detail permissions or error conditions, but the core behavioral traits are well explained.

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

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

Three sentences, each essential: purpose, idempotency and side effect, URL format. No redundancy or fluff. Front-loaded with the core verb and resource.

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 a single parameter, no annotations, and an output schema (mentioned in context), the description covers idempotency, background push, and return value structure. It is entirely adequate for an agent to understand the tool's 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% (file_id described as 'File UUID to publish'). The description adds context about the overall operation but does not provide additional parameter-specific meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'publish' and the resource 'shared file', and specifies the exact output: generate public share token, slug, and URL. This fully distinguishes it from sibling tools like file_unpublish.

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

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

The description implies the tool is used to make a file publicly accessible, but it does not explicitly state when to use it versus alternatives (e.g., file_get or file_unpublish). Some guidance on prerequisites or when not to use would improve clarity.

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

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

With no annotations, the description fully discloses key behaviors: share token retention for audit, public route returning 404, and best-effort removal of mirrored objects. This adds value beyond the input schema by revealing side effects and failure modes.

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: the first delivers the core purpose, the second adds crucial behavioral details. No redundancy or unnecessary text. Front-loaded and efficient.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers all necessary aspects: action, side effects, audit trail, and security implication. Complete for an unpublish operation.

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

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

Schema coverage is 100% with a description for file_id. The description adds no further detail about the parameter; it only restates the context. Baseline 3 is appropriate as the description does not enhance schema-provided 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 uses a specific verb ('Revoke public access') and resource ('a shared file'), clearly stating the result (visibility back to private). The name file_unpublish directly contrasts with its sibling file_publish, providing clear differentiation.

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

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

The description implies this tool is used when public access should be removed, contrasting with file_publish. However, it does not explicitly state when not to use it or mention alternative approaches, though the context is clear enough for an agent.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It reveals that the tool appends rather than overwrites, sets version to prior max + 1, eagerly mirrors published files to the Railway bucket, and never mutates old versions. However, it does not mention error conditions (e.g., nonexistent file) or permission requirements, which would improve 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 concise with two sentences: the first clearly states the core action, and the second adds a key behavioral detail. Every sentence earns its place with no redundancy or fluff.

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

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

Given that the tool has 4 parameters, schema coverage is complete, and an output schema exists, the description provides sufficient context about the update mechanism, versioning, and mirroring behavior. It lacks coverage of preconditions (e.g., file must exist and not be in archived state), but overall it is comprehensive enough for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description explains the overall versioning behavior but adds little parameter-specific meaning beyond what the schema already provides. It helps clarify that 'content' is the new file body and that file_id identifies the existing file, but does not elaborate on optional parameters like agent or content_format.

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 appends a new version to an existing shared file with explicit version numbering (prior max + 1). It distinguishes itself from sibling tools like file_create (creates new files) and file_version_delete (deletes versions) by specifying the update behavior.

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 provide any guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions (e.g., file must exist and not be archived), or explicit comparison to sibling tools like file_create or file_upload_request. Agents must infer usage solely from the name and description.

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

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

No annotations are provided, so the description carries the full burden. It transparently describes the returned items (upload_url, upload_token, expires_in_seconds TTL, self-deleting Python script), explains the script behavior (reads file, POSTs, prints resulting id, deletes itself), and notes the token is single-use and expires in ~10 min. In update mode, it explains what is preserved and what happens to the bucket mirror. It could be more explicit about authorization or rate limits, but overall is highly transparent.

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

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

The description is well-structured with two clear sections: the general create workflow and the update mode. It front-loads the main purpose and key return values, then provides step-by-step usage. Every sentence adds value without redundancy. It is appropriately sized for a tool with 7 parameters and complex workflow.

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

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

Given the tool's complexity (two modes, script generation, one-time token, self-deleting script), the description is complete. It explains what the tool returns, how to use the script, and the update mode behavior. Since an output schema exists (context signals confirm), the description doesn't need to detail return values, and it appropriately focuses on behavioral workflow. No critical 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 coverage is 100%, so the baseline is 3. The description adds significant meaning beyond the schema: it explains the purpose of the tool in contrast to file_create/file_update, describes the update mode workflow, and clarifies how parameters like publish affect the returned script output. However, it could add more detail on how filename affects format sniffing or the default path. Still, the description substantially enriches the parameter semantics.

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

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

The description clearly states the tool provides a one-time uploader script to push a local file into a shared file. It distinguishes itself from file_create/file_update for large files, and explains update mode vs create mode. The verb 'get' and resource 'one-time uploader script' 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 explicitly says this is for large HTML/Markdown files that don't fit inline in file_create/file_update. It also details the update mode when to use file_id to append a new version. It gives clear guidance on when-not by referencing the alternatives for inline content.

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

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

With no annotations, the description fully discloses behavioral traits: destructive and irreversible action, the refusal condition, the side effect of bumping current_version and re-publishing for consistency, and the return fields. This is comprehensive and leaves no hidden consequences.

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 focused paragraph of 4 sentences, front-loading the tool's destructive nature followed by constraints and side effects. It ends with return values. It is efficient but slightly dense; a more structured format (e.g., bullet points) could improve scannability, but it is not verbose.

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

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

Given the tool's simplicity (2 parameters, clear schema, output schema exists), the description fully covers purpose, constraints, side effects, and return fields. There are no gaps; the agent has sufficient information to decide and invoke correctly.

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

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

The input schema has 100% coverage with descriptions for file_id and version. The description does not add meaning beyond the schema—it mentions 'current_version' as a side effect but does not elaborate on the parameters themselves. Baseline 3 is appropriate when schema carries full definition.

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

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

The description clearly identifies the tool as deleting a single version of a shared file, with explicit notes on destructiveness and irreversibility. The verb 'delete' and resource 'single version' are specific, distinguishing it from sibling tools like file_update or file_archive.

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 conveys a clear context for use (delete a specific version) and a key constraint (refuses to delete the only remaining version). However, it does not explicitly guide when to use an alternative tool (e.g., file_archive for whole-file deletion or file_update for metadata changes), leaving some ambiguity for the agent.

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

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

Since there are no annotations, the description bears full burden. It fully discloses key behaviors: the return format (status, version, components), how optional dependencies report 'disabled' without degrading overall status, that it is always cheap, and safe for frequent polling. No contradictions.

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 concise—three short sentences plus a code block—and front-loads the essential point ('Liveness + dependency probe'). Every sentence adds unique information with no waste.

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?

Despite having no parameters, the tool is a health check with a well-documented output schema. The description is complete: it covers purpose, return shape, component behavior, cost characteristics, and use cases. With rich context signals, nothing is missing.

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

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

The input schema has zero parameters and schema description coverage is 100%, so the baseline is 4. The description adds value by explaining the output structure and behavior, meaning it exceeds the baseline.

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

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

The description clearly states it is a 'Liveness + dependency probe' and specifies the tool's purpose: checking health status of the system and its components. It distinguishes itself from the many sibling tools by being a non-mutating, informational probe.

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 explicit usage guidance: it is 'Always cheap; safe to poll on a 10s interval. Used by Docker healthcheck and the /health HTTP route.' Although it does not mention when not to use it or alternatives among siblings (none are directly comparable), the guidance is detailed and clear for a health check tool.

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

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

With no annotations, the description carries full burden. It discloses that only the caller's own OAuth connections and shared org-scoped connectors are listed, omitting others. This is a key behavioral trait. However, it does not mention pagination, ordering, or rate limits, though for a zero-param read tool this is acceptable.

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

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

Three sentences: first states the action, second lists returned fields and filtering rules, third provides usage direction. No redundant words, all earn their place.

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

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

For a parameterless list tool with an output schema, the description covers return fields, filtering logic, and usage context comprehensively. No 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?

No parameters exist, so baseline is 4 per guidelines. The description adds value by explaining the scope of the returned list and the fields, which is beyond the schema's empty structure.

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 'List the Gmail/Slack/Discord integrations this caller may use' and specifies returned fields. It differentiates from sibling tools by targeting discovery for 'integration_search' / 'integration_send' calls, making the purpose distinct.

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

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

Explicitly tells when to use: to discover which integration to target for integration_search/integration_send. Also explains what is omitted (other people's connections) and why, providing clear context and 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?

Discloses a key side-effect: ingesting the message body as a semantic memory (source='connector'), including privacy scoping (private vs shared brain). This is valuable beyond annotations which are absent. However, does not mention any destructive or mutation side-effects beyond memory ingestion.

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

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

Three focused sentences with zero fluff: first sentence defines purpose, second and third explain the memory ingestion side-effect and privacy scoping. 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 a read tool with a rich output schema (implied by context signals), the description is complete: explains purpose, side-effects, and scope. Could mention what happens on errors or if the message doesn't exist, but basic completeness is achieved.

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 schema already describes each parameter well. The description adds context about side-effects but does not add to parameter meaning beyond what the schema provides. Still, baseline is 3 and the description adds enough to reach 4.

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

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

The first sentence clearly states what the tool does with a specific verb ('Fetch') and resources ('message/thread from Gmail/Slack/Discord'), distinguishing it from sibling tools like integration_send (which sends messages) and integration_search (which searches messages).

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

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

The description implies usage for reading a single message from connected accounts, but doesn't explicitly guide when to use this vs integration_search or integration_list, nor does it mention when not to use it.

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

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

No annotations are provided, so the description carries full responsibility. It discloses that 'Reads do not ingest' (read-only) and explains the raw hit format per provider. This is sufficient for basic transparency, but it omits prerequisites (e.g., need for established connections) or potential failure modes, which would improve the score.

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

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

The description is two sentences, directly addressing purpose and return information. It is front-loaded with the core action and wastes no words. Ideal conciseness.

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

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

Given the presence of an output schema (reducing need to describe returns), the description covers purpose, usage context, behavioral traits, and alternatives. It is nearly complete, but could benefit from explicitly noting that the tool requires existing integrations and that queries use provider-specific syntax.

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

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

With 100% schema description coverage, the schema already documents all four parameters. The description adds context about the return format and query syntax nuances but does not significantly enhance parameter understanding beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly specifies the verb 'Live-search' and the resources 'connected Gmail/Slack/Discord account'. It distinguishes itself from memory recall and integration_read, making the tool's purpose unambiguous relative to 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?

The description states when to use this tool (live search of integrations) and explicitly contrasts it with memory recall and integration_read. It does not, however, provide a comprehensive list of when not to use it or address alternatives like integration_list or integration_send, so guidance is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden of disclosing side effects. It explicitly reveals that sends are audited and logged as an episodic timeline event, and that the action is restricted to the user's own connections. It doesn't mention rate limits or irreversibility, but the key behavioral traits are covered.

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

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

The description is two short, focused sentences. The first sentence front-loads the primary action, and the second adds essential constraints and audit context. Every word earns its place with no fluff or repetition.

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

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

Given the output schema exists and the input schema covers all parameters, the description needs only to provide high-level context. It does: it explains the sender scope and audit trail, and the restrictions are critical for a user to safely invoke the tool. No major gaps are apparent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any extra parameter semantics beyond the schema; it only reinforces the sender constraints, which is useful but not necessary for parameter understanding.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Send an email (gmail) or post a Slack/Discord message as *your* connected account.' It distinguishes itself from sibling tools (integration_list, integration_read, integration_search) by being the outgoing send action, and it scopes the action to the user's own connected account.

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 explicit usage context: only your own connections and shared org-scoped connectors can be used, and you can never send as another person. This gives clear boundaries for when to use the tool, though it doesn't explicitly mention alternatives by name; the sibling names make the distinction obvious.

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?

Although no annotations are provided, the description discloses the authentication flow: email sends a code, code verification, optional org selection, and session persistence. It warns 'Do not store the code or any token.' However, it does not mention error handling, code expiration, or rate limits, which would improve 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 concise (about 100 words) and well-structured with numbered steps and bullet points. It front-loads the purpose and immediately provides actionable instructions. Every sentence contributes meaningfully.

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

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

The tool has an output schema, so the description does not need to explain return values. The description covers the multi-step protocol, including status codes and session implications. It is nearly complete but could briefly mention error scenarios (e.g., invalid code, timeout) to fully prepare the agent.

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 descriptions are already detailed (e.g., 'One-time code from the login email...'). The tool description adds value by explaining the order of calls and the relationship between parameters and status codes, which is not present in the schema alone.

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

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

The description states 'Sign this MCP session in with email + OTP' and distinguishes this tool from the preferred browser OAuth flow ('Cursor desktop Connect (browser OAuth) is preferred when available'). It clearly specifies the verb, resource, and method, making it 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 explicitly says when to use this tool ('Cloud agents do not get a host mcp_auth helper — call this tool instead') and when not to ('Cursor desktop Connect is preferred when available'). It also provides a numbered step-by-step usage guide, leaving no room for misinterpretation.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states that the tool executes an action and writes an audit log, but omits critical details: whether the action is destructive, reversible, requires special permissions, or what the output schema describes. The description is insufficient for a mutation tool.

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

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

The description is a single, efficient sentence with no wasted words. However, given the tool's complexity (4 parameters, output schema, many siblings), it may be overly terse, sacrificing necessary detail. Still, it is well-front-loaded.

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

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

The tool has 4 parameters, an output schema, and a large set of sibling tools, yet the description provides only a vague purpose. It does not explain what a 'governed ontology action' is, how to specify the action, what the parameters object should contain, or what the output represents. The description is incomplete for the 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%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides (e.g., 'agent' is an override, 'action_name' is a registered type). No extra constraints, examples, or usage hints are given.

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-resource pair ('Execute a governed ontology action') and mentions a clear side effect ('write an audit log entry'). It is distinguishable from many sibling tools (e.g., memory_remember, memory_forget) but could be more explicit about what a 'governed ontology action' entails, leaving some ambiguity.

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, when not to use it, or how it relates to sibling tools like memory_action_log_list or memory_remember. The agent receives no contextual decision-making 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?

Without annotations, the description carries the full burden of behavioral disclosure. It only states the basic action and scope but omits details like ordering, recency definition, read-only nature, pagination, or auth requirements. The lack of behavioral context impairs safe tool selection.

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 very concise (one short sentence) but under-specified. While brevity is positive, it does not earn its place because it omits critical information that a longer description would provide. Conciseness should not come at the cost of completeness.

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 low complexity (one optional parameter, output schema present), the description should still clarify what 'governed action executions' are and what 'recent' means. The current text is too minimal to guide an agent effectively, even with the output schema providing return structure.

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 0% (no parameter descriptions in schema). The description fails to mention the 'limit' parameter at all, providing no added meaning beyond the schema's default, min, and max constraints. This leaves agents unaware of how to control result volume.

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 ('List') and resource ('governed action executions for the org'), making the tool's purpose clear. It distinguishes itself from sibling tools like memory_episodes_list or memory_skills_list by targeting a distinct entity type.

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 provided on when to use this tool versus alternatives. The description does not mention context, exclusions, or comparisons with related tools such as memory_action_apply or other list tools.

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?

Without annotations, the description carries full burden and does well: it explains the multi-pillar parallel retrieval process, ranking, packing into a sectioned markdown bundle, and lists output fields. Minor gap: no mention of permissions or potential side effects, but overall strong for a read-heavy 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?

Two concise paragraphs: first paragraph states purpose and process, second paragraph gives usage guidance and return fields. Every sentence adds value, no redundancy. Well front-loaded.

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

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

Given parameter count 6, 100% schema coverage, and an output schema existing, the description completes the picture by aggregating purpose, process, usage context, alternative guidance, and expected output fields. No 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 100%, so baseline is 3. The description adds value by explaining that 'repo' boosts repo-scoped memories and 'open_files' seeds graph-relationship lookup, which goes beyond the schema's basic descriptions. However, it does not elaborate on all parameters; still earns a 4 for meaningful additions.

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 'Assemble one token-budgeted, cited context pack for a task' using a specific verb ('assemble') and resource ('context pack'), and distinguishes it from siblings like memory_recall, memory_procedure_get, and memory_graph_related by explicitly noting it replaces serial calls.

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 to use this 'once at the start of a task instead of issuing serial memory_recall / memory_procedure_get / memory_graph_related calls', providing clear when-to-use and when-not-to-use guidance, with alternatives named.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It does not mention side effects (e.g., whether this view is read-only or changes state), authorization needs (e.g., does it require access to wiki, memories, graph, work?), or failure behavior (what happens if the slug is invalid?). The description is silent on these critical behavioral traits.

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 communicates the core function without extraneous details. It effectively front-loads the purpose. Minor deduction for the imprecise verb 'roll up' but overall very efficient.

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

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

Given the tool has an output schema (mitigating the need to describe return values), only one simple parameter, and the description broadly lists the data sources aggregated, the description is adequate. However, it lacks behavioral context (e.g., performance implications, data freshness) that would help an agent gauge suitability, bringing it down from a higher score.

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% description coverage for the single parameter 'slug', so the baseline is 3. The description does not add any additional semantics beyond what the schema already states about the slug parameter. No improvement or degradation.

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 verb ('roll up') and clearly identifies the resource (wiki, memories, graph neighbors, work) for one entity, which distinguishes it from related siblings like 'memory_recall' or 'memory_graph_related'. However, the verb 'roll up' is somewhat colloquial; a more precise verb like 'aggregate' or 'retrieve' would be even 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 implies use when you need a composite view of an entity across multiple data sources, but it gives no explicit guidance on when not to use it or what alternatives exist. For example, it doesn't mention that 'memory_recall' might be better for pure recall or that 'memory_graph_related' might be preferred for graph neighbors alone.

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

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

No annotations are provided, so the description carries the full burden. It states the default scope (shared within the org), which is useful, but does not disclose behavioral aspects like ordering, pagination behavior, or whether results are read-only. The output schema exists but the description offers no additional transparency beyond the schema.

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

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

The description is very concise (one short sentence) and front-loads the core purpose. It covers the essential behavior without extraneous words. However, it could be slightly more specific about the result set (e.g., chronological order) without losing brevity.

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

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

Given the output schema exists and the parameter schema is well-documented, the description is minimally adequate. However, it lacks context about ordering (presumably chronological), whether updates to episodes affect the timeline, or how pagination works (limit suggests a list but no offset or cursor). For a tool with 5 parameters and a non-trivial output, more completeness would help.

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

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

The schema already provides detailed descriptions for 80% of parameters (agent, since, topic, until, limit). The description adds no additional parameter meaning beyond what the schema offers. With schema_coverage at 80%, baseline 3 is appropriate.

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

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

The description clearly states the tool browses an episodic timeline, specifying scope (shared within the org by default). This distinguishes it from other memory-related tools like memory_recall or memory_entity_view, though it does not explicitly contrast with 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?

The description implies the tool is for browsing timelines shared at the org level, and the schema provides filter parameters, but there is no explicit guidance on when to use this versus other memory browsing tools (e.g., memory_recall, memory_assemble_context) or when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the soft-delete nature, required permission, the format of memory_id, and what is not supported. It does not mention side effects or reversibility, but the level of detail is good for a deletion tool.

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

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

The description is two concise sentences plus a well-placed clarification note. Every sentence serves a purpose: purpose, permission, parameter guidance, and exclusion. No wasted words.

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 2-parameter tool with an output schema and clear siblings, the description covers purpose, parameter semantics, permissions, and limitations. It could briefly mention what the output looks like, but the output schema likely handles that. Overall, it provides enough context for correct invocation.

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

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

Both parameters (reason, memory_id) are described in the schema with 100% coverage. The description adds value by clarifying that memory_id is the UUID from memory_recall (not a Mem0 id post-G2) and that reason is an audit requirement. This enriches the schema 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 tool soft-deletes a semantic/episodic memory by ID, requiring the 'memory:delete' permission. It distinguishes itself from siblings like 'memory_forget_procedure' and 'memory_forget_skill' by explicitly specifying the memory subtype.

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

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

The description provides context that the memory_id is the UUID from memory_recall and notes that procedural deletes are not supported via this tool. While it does not explicitly state when to use this over siblings, the mention of semantic/episodic memory and the exclusion of procedural deletes offers sufficient guidance.

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

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

No annotations are provided, so the description carries full responsibility. While it mentions 'soft-delete', it does not explain what this entails (e.g., recoverability, cascading effects, or how it differs from a hard delete). The term 'all active versions' hints at versioning but lacks detail. For a destructive operation, this transparency is insufficient.

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, well-structured sentence that conveys the essential action and scope. There is no unnecessary information, and every word contributes to purpose clarity.

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

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

An output schema exists but is not visible in the input. The description does not mention return values, but the schema may cover that. Missing context includes behavioral details (e.g., is the operation idempotent? what happens if no active versions exist?), and no differentiation from sibling deletion tools beyond the resource name. The description is adequate for a simple operation but lacks depth for a deletion tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the nuance of 'all active versions' and clarifies deletion 'by name', which is not explicit in the schema description for the 'name' parameter. However, it does not add meaning beyond the schema for the 'reason' parameter, and the overall added value is marginal.

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 ('soft-delete'), the resource ('all active versions of a playbook'), and the key discriminator ('by name'). This distinguishes it from sibling tools like 'memory_forget' and 'memory_forget_skill' which target different resources.

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 provide explicit guidance on when to use this tool versus alternatives like 'memory_forget' or 'memory_forget_skill'. The purpose is clear from the name and description, but no contextual cues or exclusions are offered.

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

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

No annotations are present, so the description carries full burden. It states 'soft-delete' but does not explain what this entails (e.g., reversibility, visibility of soft-deleted skills, side effects on associated data). Critical behavioral context is 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 description is a single, front-loaded sentence that efficiently states the core action. However, it could be slightly expanded to include essential behavioral notes without losing conciseness.

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

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

Despite having an output schema (not shown), the description lacks details about the effect of soft-deletion, return value, or how to interact with the result. For a tool with two required parameters and a specific action, this is insufficient for confident use.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The tool description adds no new meaning beyond what the schema provides (e.g., does not explain why 'reason' is required or how it is used). 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 'Soft-delete all active versions of a skill by name' uses a specific verb (soft-delete) and resource (all active versions of a skill by name), clearly distinguishing from siblings like memory_forget (which might target other entities) and memory_skill_get (read-only).

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 provided on when to use this tool versus alternatives (e.g., memory_forget, memory_skill_set). There is no mention of prerequisites, restoration options, or when soft-deletion is preferred over hard-deletion.

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?

Even without annotations, the description clearly states that the tool is a no-op when the graph store isn't enabled, and that the predicate must be a registered link type. It also implies that the operation is not destructive beyond adding a link. The transparency is high for a write operation with no 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 three sentences, each earning its place: purpose, behavioral nuance (no-op), and usage guidance (when to use, predicate requirement). There is no fluff or repetition of schema details.

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 presence of an output schema and good schema coverage (83% described), the description is complete. It explains the core behavior, the edge case (graph not enabled), and the constraint on predicate. The sibling list includes `memory_graph_related`, and the description does not need to elaborate on return values since an output schema exists.

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

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

Schema coverage is 83%, and the description adds meaning beyond the schema by explaining that `predicate` must be a registered link type, which the schema does not mention. It also implies that `subject`, `predicate`, and `object_entity` are the core parameters, while `agent` and `weight` are optional modifiers. The description compensates for the missing schema detail on `object_entity` being the target.

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 'Record' with 'explicit relationship in the optional org-scoped graph store'. It clearly distinguishes from other memory tools by mentioning 'vector recall would obscure' and contrasting with siblings like `memory_recall` and `memory_remember`. The no-op characteristic when graph is not enabled is also clearly stated.

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

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

The description explicitly says when to use ('when you learn a structured fact') and when not to use (when graph isn't enabled, it's a no-op). It provides a clear alternative pattern by referencing `memory_ontology_list` for registered predicates. However, it does not explicitly mention when NOT to use this tool compared to `memory_remember` or `memory_recall`.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It clearly indicates the tool performs a read operation (returns entities) and mentions the `depth` parameter constrains traversal. It could be improved by noting whether the result includes the original entity or only neighbors, but overall it discloses key behavioral aspects sufficiently for agent decision-making.

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 of 17 words, front-loading the core purpose and referencing both key parameters. Every word is necessary, and there is no superfluous 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?

Given the tool has an output schema (not provided in detail but indicated as existing), the description does not need to explain return values. The description is adequate for a graph traversal tool with three parameters; however, it could be more complete by clarifying the traversal behavior (e.g., BFS/DFS, deduplication) and whether cycles are handled, but this is not essential for basic use.

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

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

Schema description coverage is only 33%, meaning the schema only documents the `name` parameter. The description compensates by explaining how `name` and `depth` are used in the graph traversal. However, it does not mention the `limit` parameter, leaving its role unclear; a brief note on limiting returned results would improve this.

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 returns entities related to a given name via a graph store, up to a specified depth. This is a specific verb+resource description that distinguishes it from siblings like `memory_graph_relate` (which likely creates relationships) and other memory tools. However, it could be slightly more explicit by mentioning it performs a traversal or expansion, not just a lookup.

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

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

The description implies when to use this tool: when you need to find related entities in the graph store. However, it provides no guidance on when not to use it (e.g., if you only need direct relationships, use a different tool) or alternatives among siblings such as `memory_entity_view` for single entity details or `memory_recall` for general memory retrieval.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure, but it only states 'Register or update a custom org link type.' It fails to disclose whether the operation is destructive (e.g., overwrites existing configuration), what the return value contains, or any authorization requirements. This is insufficient for safe agent invocation.

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

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

The description is a single front-loaded sentence that efficiently conveys the core purpose. It earns its place, but could be slightly expanded to include key behavioral notes without losing conciseness.

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

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

Given the tool has 6 parameters, an output schema, and an ontology domain with many related tools, the description is far too sparse. It does not explain what a 'link type' is, how it relates to object kinds, or when cardinality options apply, leaving an agent underinformed for correct selection and 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?

Since schema description coverage is 100%, the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions, such as explaining the relationship between 'cardinality' and 'to_kinds/from_kinds.' It does not extend or clarify the schema's definitions.

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 ('Register or update') and resource ('custom org link type'), effectively communicating what the tool does. However, it does not explicitly distinguish this tool from sibling ontology tools like memory_ontology_object_kind_set or memory_graph_relate, preventing a perfect score.

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 memory_graph_relate or memory_ontology_propose_entity. There is no mention of prerequisites, upsert behavior, or exclusion criteria, leaving the agent without decision-making context.

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

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

No annotations are provided, so the description must convey behavioral traits. It states 'List', which weakly implies a read-only operation, but does not explicitly confirm safety, side-effect freedom, or performance characteristics. A clearer statement about non-destructiveness and read-only nature would be warranted given the absence of 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, front-loaded sentence that conveys the essential information without any filler. Every word earns its place, listing the action, resource, and components in a compact format.

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 parameters and an existing output schema, the description adequately covers the tool's scope by naming the four categories of schema items. It could be slightly more complete by mentioning that this returns definitions (not instances) or that it is read-only, but overall it provides sufficient context for an agent to understand when to invoke it.

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

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

There are zero parameters, so the baseline score is 4. The description does not need to add parameter-level details because none exist. The schema coverage is already 100% by definition.

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 ('List') and the resource ('org ontology schema'), and enumerates the specific components (link types, object kinds, interfaces, action types). This differentiates it from sibling tools like memory_ontology_link_type_set and memory_ontology_object_kind_set, which perform modifications rather than 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?

No explicit guidance on when to use this tool versus alternatives is provided. The context implies it is for reading the ontology schema, but there is no mention of prerequisites, when not to use it, or hints about alternatives. For a simple listing tool, the lack of guidance is acceptable but not outstanding.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the merge involves remapping foreign keys and deleting the duplicate entity, which is an irreversible destructive action. This sufficiently signals the irreversible merge behavior to an AI agent, though it could add notes about required permissions or rollback inability.

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

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

The description is a single, front-loaded sentence with no wasted words. It clearly conveys the action (merge), the two critical slugs, and the side effects (remap, delete). Every part 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?

Given the tool has 3 parameters (2 required), 100% schema coverage, and no nested objects, the description is complete enough for an agent to understand the core operation. It does not explain the return value (output schema exists but not described), but the merge-and-remap behavior is the key context. The tool is straightforward enough that no major gaps exist.

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 description for each parameter is already informative (e.g., 'Duplicate entity slug to merge away', 'Canonical entity slug to keep'). The tool description adds marginal value by framing the operation as 'merge A into B', but the schema itself already explains the roles. The 'agent' parameter is not mentioned in the description, but its purpose is self-evident from 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 uses a specific verb ('merge') and explicitly names the two resources involved ('drop_slug' and 'keep_slug'), while parenthetically explaining the core behavior (remap FKs, delete duplicate). This clearly distinguishes it from sibling tools like memory_entity_view or memory_graph_relate.

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

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

The description implies when to use this tool (when you have duplicate entities and need to merge one into another), but it does not explicitly state when NOT to use it, nor does it name any alternative tools for handling entities differently (e.g., memory_entity_view or memory_forget). A 'when-not' or prerequisite about ensuring slug validity would improve clarity.

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

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

No annotations are provided, so the description should disclose behavioral traits. It implies an idempotent upsert ('register or update') but does not explain side effects, whether it overwrites existing schemas, permission needs, or behavior when the object kind already exists. Minimal behavioral disclosure.

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

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

One short sentence, no fluff, front-loaded with the action. Efficiently communicates the core purpose in minimal space.

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?

Despite having an output schema, the description is too thin for a tool that defines a custom ontology kind with a properties schema. It lacks context about what 'object kind' means in the ontology, how properties_schema is applied, or relationship to other ontology tools. An agent would likely need to inspect the schema and sibling tools to understand 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?

Schema description coverage is 100% with descriptions for all parameters, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides (e.g., name is the kind name, properties_schema is a JSON schema). No added semantic 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?

Description uses specific verb 'Register or update' with resource 'custom org object kind', clearly distinguishing it from sibling tools like memory_ontology_list (list) and memory_ontology_link_type_set (set link types). It is concise 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?

No guidance on when to use this tool instead of alternatives like memory_ontology_merge_entities or memory_ontology_rekind_entity. Does not mention prerequisites, context, or scenarios. The single sentence provides no 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?

No annotations are provided, so the description carries full responsibility. It notes the entity is active immediately, which is useful, but does not disclose important behavioral traits such as whether the operation is idempotent, what happens if the entity already exists, whether permissions are needed, or side effects on related entities.

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 of 31 words, front-loading the purpose. It is concise, but it could be slightly more efficient by omitting 'typed' if 'ontology entity' already implies typing, or by adding a short note on typical use.

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 complexity of operating on an ontology (with kind, properties, agent overrides) and the presence of an output schema covering the return, the description is minimally adequate. It identifies the key parameters but lacks context on what a 'typed ontology entity' is, how 'kind' relates to object_kind_set, or validation requirements. The rich sibling list suggests more contextual background is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by indicating the effect (active immediately) and by tying the 'name', 'kind_name'/'kind', and 'properties' parameters to the ontology context. The brief description compensates well for the overloaded 'kind' parameter, which has an alias, and the open-ended 'properties' object.

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 'Propose a typed ontology entity (active immediately)' uses the verb 'propose' and the resource 'typed ontology entity', making the action clear. It also adds the behavioral detail that the entity becomes active immediately, distinguishing it from similar tools like memory_ontology_merge_entities or memory_ontology_rekind_entity, though it doesn't explicitly tie to the 'memory_' family.

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

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

There is no guidance on when to use this tool versus similar ontology or memory tools (e.g., memory_ontology_merge_entities, memory_entity_view, memory_remember). No alternatives or usage context are provided, leaving the agent to infer based on the name alone.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states only 'Change the object kind' without revealing side effects, permissions, or impacts on relationships or properties. The minimal description fails to convey the mutation's scope or 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 description is a single, front-loaded sentence with no wasted words. However, it is extremely terse and lacks any structure (e.g., separate sections, bullet points). For a tool with 4 parameters, it could benefit from slightly more structure while remaining concise.

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 complexity (4 parameters, output schema exists), the description is insufficient. It does not explain the ontology domain, the meaning of 'object kind', or how this tool fits into the entity lifecycle. The sister tools suggest a richer context that is not captured here.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds no additional meaning beyond the schema; it does not explain the role of 'kind', 'kind_name', 'agent', or 'slug'. Baseline 3 is appropriate since the schema carries the burden.

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

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

The description 'Change the object kind of an existing ontology entity' clearly identifies the verb (change) and resource (object kind of an ontology entity). It is specific and distinct from sibling tools like memory_ontology_merge_entities or memory_ontology_propose_entity, though it does not explicitly differentiate from the close sibling memory_ontology_object_kind_set.

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

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

The description provides no guidance on when to use this tool versus alternatives. It lacks context such as prerequisites (e.g., entity must exist, kind must be registered) or any indication of when rekind is appropriate compared to other memory ontology tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'alias' and does not mention read/write nature, side effects, return format, or any other behavioral traits. The agent is left without information about what actually happens when invoking this tool.

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

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

The description is a single short sentence, which is concise, but it is under-specified rather than efficiently informative. It reveals only that this tool is an alias, providing minimal value. The brevity is acceptable, but the content is too sparse to be considered well-structured.

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

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

Given the tool is a simple getter with an output schema, some incompleteness is tolerable, but the description fails to even state what the tool retrieves. It depends entirely on the agent knowing memory_procedure_get, which is not a safe assumption. The description is not sufficient for a new 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%, so the baseline is 3. The description adds no extra meaning beyond the schema, but the schema already documents each parameter (name, version, expand_skills) adequately. There is no contradiction or omission in the schema, so a neutral baseline 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 is merely 'Alias for memory_procedure_get' and does not state the actual function (e.g., 'Retrieves a playbook by name'). It references another tool without explaining what that tool does, leaving the agent to infer purpose from the tool name and sibling list. This is better than a pure tautology but still lacks a clear verb+resource statement.

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 memory_procedure_get or other retrieval tools. Since it is an alias, one might assume interchangeability, but the description does not explicitly say so. There is no context about scenarios where this alias should be preferred.

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?

Since no annotations are provided, the description must disclose behavioral traits like whether the tool is destructive, idempotent, or requires authentication. The description offers nothing except an alias reference, leaving all behavioral characteristics opaque. This is a significant gap.

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

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

The description is extremely short (one sentence of six words). While this is concise, it is under-specified—there is no detail about what the tool actually does. Conciseness is not achieved at the expense of completeness; the description fails to communicate purpose, hence the score is slightly above average only for brevity.

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 complexity (6 params, 1 required, no annotations, output schema present), the description is radically incomplete. It provides no functional context, no explanation of what a 'playbook' is, how it relates to 'procedure,' or what the output schema represents. The agent cannot use this tool effectively based solely on the description.

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

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

Schema description coverage is 100%, so the schema itself documents all six parameters adequately (e.g., 'name' as 'Playbook name (stable id)'). The description adds no extra meaning, but the baseline of 3 is appropriate since the schema already carries the burden. However, for an alias tool, some cross-reference or note about mapping to memory_procedure_set parameters would add 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?

The description says 'Alias for memory_procedure_set.' This does not specify what the tool itself does; it merely points to another tool. Without knowledge of memory_procedure_set, the purpose is completely unclear, and there is no distinct verb or resource described for memory_playbook_set.

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

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

The description provides no guidance on when or why to use this tool instead of alternatives. It does not mention any context, exclusions, or refer to sibling tools like memory_procedure_set. An agent has no way to decide between this and similar memory tools.

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

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

No annotations are provided, so the description bears full responsibility. It only states it is an alias, with no disclosure of side effects, authentication, rate limits, or return behavior. The agent learns nothing about cautions or state changes.

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 very short but uninformative. It passes on the burden to another tool without adding independent value. Being an alias is useful to know, but the description is too brief to stand alone.

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

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

Given the tool has 4 optional parameters, an output schema, and a complex domain (playbooks vs procedures), the description is incomplete. It fails to differentiate from siblings like memory_procedures_list or describe when to use it. The agent needs more to decide 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 50%, so the schema already describes some parameters (e.g., tag filter, include_body). The description adds no parameter-level meaning; the alias remark doesn't help an agent understand what each parameter does. Baseline 3 is appropriate because schema partially covers the parameters.

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

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

The description states it is an alias for ``memory_procedures_list``, which implies listing, but gives no verb or resource of its own. It relies entirely on the sibling to define purpose, which is vague on its own.

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 usage guidance, no context on when to choose this over ``memory_procedures_list``, and no mention of skipped or alternative tools. The agent is left guessing the relationship.

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?

Without any annotations, the description does well to disclose the effect of expand_skills, noting it resolves tool_recipe.skills and returns results in steps_md/content_md. It also clarifies that parameter 'version' defaults to latest active version. However, no disclosure of read-only status, auth needs, or potential errors (e.g., if playbook not found).

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 concise: two effective sentences, no filler. First sentence establishes core purpose and optional parameters; second sentence adds a key behavioral detail. Every word 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?

Given the presence of an output schema, the description doesn't need to explain return values. However, with no annotations and complex siblings, the description misses important context: whether this is a read-only operation, what happens on missing name, or how it differs from memory_playbook_get (sibling). Adequate but has clear gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for expand_skills (explains what happens when true) and hints that version is optional with default behavior. But 'playbook' vs 'procedure' terminology may confuse a model. Does not explain the output schema or interpretation of returned object.

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 'Fetch a stored playbook by name (and optionally version)', which uses a specific verb ('Fetch') and resource ('playbook'). This distinguishes it from siblings like memory_procedure_set (write operation). The mention of 'playbook' instead of 'procedure' causes minor ambiguity, but title consistent with name 'memory_procedure_get'.

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 options like optional version and expand_skills, but provides no guidance on when to use this tool versus siblings like memory_playbook_get or memory_procedures_list. The sibling context shows many similar tools (e.g., memory_skill_get, memory_procedures_list), yet no exclusion or context is given.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It reveals that each call creates a new version, that the tool is routed through a 'guarded ingestion pipeline', and that it returns a status ('active' or 'duplicate'). This is adequate but lacks details on permissions, side effects on old versions, or rate limits.

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

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

The description is concise: three sentences, no wasted words. The primary action is front-loaded ('Insert a new version of a procedure'), and each sentence serves a clear purpose (versioning, parameter explanation, return value).

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 six parameters, output schema existence, and no annotations, the description covers the key aspects: versioning behavior, playbook structure, and return status. It omits explicit prerequisites or workflow integration with related tools, but it is sufficient for a setter tool with high schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the playbook concept for tool_recipe and steps_md, but it does not significantly enhance understanding of the other parameters (name, tags, agent, description) 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 clearly states the action: 'Insert a new version of a procedure. Each call creates a new version.' It uses a specific verb ('insert') and resource ('procedure'), and distinguishes itself from sibling tools like memory_procedure_get (retrieve) and memory_forget_procedure (delete) by focusing on creation/versioning.

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 explicit guidance on when to use this tool vs alternatives such as memory_skill_set or memory_playbook_set. The description mentions 'playbooks' but does not clarify when a procedure vs a playbook should be used. There is no 'when-not-to-use' or alternative tool naming.

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

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

With no annotations, the description must disclose behavioral traits, but it only states the basic purpose. It does not mention read-only nature, authentication requirements, pagination behavior, error cases, or what happens with no results. The schema hints at pagination but the description omits this.

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 that front-loads the action and resource. It is concise but lacks any structure (e.g., parameter details, usage notes). It could be slightly expanded without harming conciseness.

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

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

Given the 4 parameters, existence of an output schema, and the presence of a very similar sibling, the description is insufficient. It omits guidance on pagination, filtering by tag, the effect of include_body, and the format of the output. The context is incomplete for an AI agent to reliably invoke 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?

Schema description coverage is 75%, and the description adds no additional meaning to the parameters. For example, 'limit' and 'offset' are self-explanatory from the schema, but the description does not clarify semantic distinctions or usage patterns.

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

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

The description clearly states it lists playbooks (latest version) in the caller's org. However, the tool name 'memory_procedures_list' conflicts with the description mentioning 'playbooks', and there is a sibling 'memory_playbooks_list' that likely does something similar, but no differentiation is provided.

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 'memory_playbooks_list'. There is no mention of prerequisites, context, or conditions that favor this tool over siblings.

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

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

No annotations exist, so the description carries the full burden. It explicitly states behavior: default scope is durable pillars (semantic, episodic, procedural, skill, strategic, work), working memory is omitted by default, `agent` filter only applies to semantic/episodic, and `repo` boosts but doesn't hide. These disclosures are clear and comprehensive, though it doesn't address auth needs or rate limits directly. The description does not contradict any annotations since none are provided.

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 concise—only 4 short sentences—yet packs essential usage guidance, default scoping, parameter advice, and a nuanced note about `agent` and `repo`. Every sentence earns its place by providing actionable information for the AI agent. The structure is front-loaded with the core purpose, followed by parameter-specific guidance.

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

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

Given the tool's complexity (9 parameters, 1 required, 100% schema coverage, with output schema present) and no annotations, the description is remarkably complete. It covers default behavior, parameter interaction, filtering strategies, and troubleshooting advice. The presence of an output schema reduces the need to describe return values. The description fully equips an agent to select and invoke this tool effectively.

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 has 100% coverage with rich descriptions for each parameter, so the baseline is 3. The description adds value beyond the schema by explaining the interplay between parameters (e.g., 'Shared brain on durable pillars: pass agent="cursor" only to narrow semantic/episodic'), providing usage advice for entity questions, and clarifying that `repo` boosts but doesn't hide. This raises the score above baseline.

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

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

The description clearly states 'Hybrid recall across memory pillars within the caller's org', specifying the verb (recall), resource (memory pillars), scoping (caller's org). It differentiates from siblings like memory_remember (store) and the other memory_* tools by focusing on retrieval across multiple pillars. The inclusion of 'hybrid' adds nuance about combining durable and working scopes.

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 explicit guidance on when to use this tool vs alternatives: default scope is durable pillars only, and it advises passing `scope=["working"]` for current chat turns. It also explains when to set `agent` (shared brain on durable pillars) and gives specific strategies for entity/competitor questions (use short keyword anchor with `repo`/`github`). This helps an AI agent decide when to use this tool over others like memory_episodes_list or memory_strategic_plan_get.

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

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

With no annotations provided, the description carries full burden. It discloses the guarded ingestion pipeline (dedup, PII, injection screening, RLS) and tagging behavior. However, it does not detail durability guarantees, idempotency, or write permissions, which would have made it a 5.

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

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

The description is concise (3 sentences), front-loaded with the core purpose, and uses clear formatting (backticks). Every sentence adds distinct value without redundancy.

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

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

Given the complexity (7 params, 1 required, output schema exists), the description covers the essential behavioral aspects: allowed kinds, pipeline, and tagging. It does not explain the output schema, but that is acceptable since a separate output schema exists. Minor gap: no mention of the 'agent' or 'subject' parameters beyond schema, but schema already handles them.

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 baseline is 3. The description adds value beyond the schema by explaining the semantic pillar distinction for kinds, the rejection of procedure/skill, and the tag generation from repo/github parameters. This elevates it above the baseline.

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

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

The description clearly states 'Write a durable memory into the caller's org' (specific verb+resource). It also distinguishes from siblings by explicitly rejecting 'procedure'/'skill' kinds and directing to alternative tools (memory_procedure_set, memory_skill_set).

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

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

The description provides explicit when-to-use guidance (for fact/preference/event/note) and when-not-to-use (procedure/skill should use other tools). It also explains the tagging behavior for repo/github parameters, aiding correct invocation.

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

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

No annotations are provided, so the description carries the full burden. It effectively discloses the self-healing behavior (auto-open on expiry/closure) and the resulting response fields (new session_id, reopened flag). It also explains how repo/github/topic parameters affect scope. Missing details like rate limits or auth requirements, but the key mutation and recovery behaviors are well covered.

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

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

The description consists of two short, front-loaded sentences. The first immediately states the core purpose and the self-healing feature. The second explains the behavioral details and relevant parameters without any fluff. Every sentence earns its place, and the structure is highly efficient.

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

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

Given that no annotations exist and an output schema is present (so return values need not be detailed), the description covers the main behavior and parameter usage for reopening. It assumes knowledge of the session concept but references related tools (memory_session_open, memory_state_set) implicitly. Could have briefly mentioned the workflow (e.g., 'use after memory_session_open'), but overall it is sufficient for an agent familiar with the domain.

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% (baseline 3). The description adds meaningful context for 3 of 6 parameters (repo, github, topic) by explaining their role during reopen to preserve workspace scope and avoid manual memory_state_set. This goes beyond the schema's generic descriptions. The remaining parameters (session_id, role, content) are covered adequately by schema defaults and enums.

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: 'Append a turn to a working-memory session'. It also highlights the unique self-healing behavior that distinguishes it from other memory tools like memory_recall or memory_remember. The verb+resource specificity (append turn to session) is precise and differentiated.

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

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

The description implicitly conveys when to use this tool (for adding turns to an active session), and explains that self-healing avoids manual memory_state_set. However, it lacks explicit 'when not to use' guidance or a direct comparison with alternative tools such as memory_session_open or memory_recall. The usage context is clear but not exhaustive.

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 explains the side effect of distillation when distill is true, including that it is queued for a background worker. Given no annotations are provided, this is valuable behavioral disclosure beyond the schema.

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

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

The description is extremely concise with two short sentences, no filler, and the key action is front-loaded. Every sentence adds value.

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

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

Given the output schema exists and there are no nested objects, the description sufficiently clarifies the tool's behavior and parameter semantics. It does not need to explain return values, and the side effect is covered well.

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 good descriptions for both parameters. The description adds context about the distill parameter default and its effect (queued for background worker), but does not add significant meaning beyond the schema's existing description of 'Enqueue for distillation into semantic/episodic memory'.

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 'Close a working-memory session', using a specific verb and resource that distinguishes it from sibling tools like memory_session_open and memory_session_get. While the purpose is well-defined, it does not explicitly differentiate it from other memory session 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 mentions the distill parameter default behavior, indicating when the transcript is summarized. However, it does not provide guidance on when to use this tool versus alternatives like memory_session_ensure or memory_forget.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It describes that the tool reuses the session in the conversation/active-session state pointer if still open and owned by the caller; otherwise closes it (distilling) and opens a fresh one, updating state. It also details the return structure and explains the 'soul' field, providing good transparency about side effects and state changes.

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

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

The description is moderately compact but front-loads the key action and usage context well. Every sentence adds value, though it could be slightly more concise or structured. It includes example return format and special case explanation for 'soul' field, which is helpful but adds length.

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 7 parameters (complex but 100% schema coverage) and presence of an output schema, the description adds valuable behavioral context (e.g., session ownership and distillation) not in structured fields. It is complete enough for selecting and invoking the tool, though a bit more detail on failure modes would push to 5.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds beyond the schema by explaining that 'repo' keys the conversation/active-session state pointer, and that 'user' when set replaces a separate memory_session_append call. However, it doesn't elaborate on all parameters; incremental value over schema is moderate, warranting a 4.

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

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

The description starts with 'One-call session bootstrap: recover the active session or open one,' which clearly states the tool's verb (bootstrap, recover, open) and resource (session). It explicitly distinguishes itself from sibling tools like memory_session_get, memory_session_close, memory_session_open by noting it replaces a multi-step ritual, reducing ambiguity.

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 explicit when-to-use and when-not-to-use guidance: it states that this tool replaces the 'memory_state_get → memory_session_close → memory_session_open → memory_state_set' ritual, implying it should be used instead of that sequence. It also specifies when to pass 'fresh: true' (on the first turn of a new chat), offering clear context for usage.

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

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

No annotations are provided, so the description must carry the full transparency burden. It correctly indicates a read operation ('Read') and hints at typical turn types (debug, handoff, append failure recovery). However, it omits behavioral details such as idempotency, whether the session must be open, or what happens if the session_id is invalid. For a simple read, this is minimally sufficient but could disclose more.

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 a parenthetical for extra context. Every word earns its place; there is no redundancy or fluff. Ideal for quick parsing by an AI 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?

The tool is simple (one parameter, no enums, output schema exists). The description covers the core action and even illustrates typical turn types. While it could clarify the exact structure of the output, the presence of an output schema mitigates this gap. The description is reasonably complete for the tool's complexity level.

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

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

Schema description coverage is 100% (the single parameter session_id is documented as 'Session id from memory_session_open'). The description adds no new information about the parameter beyond what the schema already provides. Baseline of 3 is appropriate per guidelines.

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 'Read session metadata and turns', specifying a concrete verb (read) and resource (session metadata and turns). This distinguishes it from sibling write-oriented tools like memory_session_append or memory_session_close, leaving no ambiguity about its retrieval 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 provides no explicit guidance on when to use this tool versus alternatives such as memory_session_open (returns session id), memory_recall (searches episodes), or context_retrieve. The parenthetical hints at debug/recovery use cases but does not clarify when to prefer this over other read tools. The agent is left to infer selection logic.

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 any behavioral traits beyond the basic action. With no annotations provided, the burden is on the description to cover aspects like idempotency, side effects, authentication needs, or whether opening creates a new session or retrieves an existing one. None of this is addressed.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the core action and return value.

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?

Despite having 5 optional parameters and a complex set of sibling tools, the description is remarkably sparse. It omits explanation of what a working-memory session is, how TTL affects it, or what the returned session_id is used for. The presence of an output schema is not leveraged in the description.

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

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

Schema description coverage is 100%, so the input schema already documents all 5 parameters. The tool description adds no additional semantic value or usage context for any parameter, keeping the score at the baseline of 3.

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

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

The description clearly states the tool opens a working-memory session and returns a session_id. The verb 'Open' and resource 'working-memory session' are specific. However, it does not distinguish this from sibling tools like memory_session_ensure or memory_session_get, which could overlap in 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?

No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it differs from other memory session tools. The user is left to infer the context from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, if it requires authentication, or how it behaves on error (e.g., missing skill). The word 'Fetch' implies a read operation, but it is not explicit.

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 earns its place. It is front-loaded with the key action and resource. However, it could be slightly more informative without losing conciseness (e.g., noting read-only or error 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?

Given the lack of annotations and the presence of a detailed output schema, the description is too minimal. It does not explain edge cases (e.g., missing skill, invalid version), the meaning of 'latest active', or how this tool differs from other memory skill tools. The agent would need additional context to use it reliably.

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 clear parameter descriptions. The description adds no additional meaning beyond summarizing the schema ('Fetch by name and optionally version'). It does not explain what constitutes a 'skill' or the behavior of 'latest active'.

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 ('Fetch'), the resource ('a stored skill'), and the parameter ('by name (and optionally version)'). This is specific and distinguishes it from sibling tools like memory_skills_list (list all) or memory_skill_set (create/update).

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 provided on when to use this tool versus alternatives (e.g., memory_skill_resolve, memory_skills_list). The description does not mention when to use the version parameter or what happens if the skill is not found. Usage context is entirely implied.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It clearly states the tool resolves references (input) to full records (output), implying a transformation/lookup behavior without destruction. It does not disclose error behavior (e.g., missing skill refs) or side effects, but for a resolution task it is reasonably transparent.

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

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

The description is a single, front-loaded sentence that efficiently states the purpose. It wastes no words. However, it uses backticks for internal references (e.g., 'tool_recipe.skills'), which may be slightly less readable for an AI agent, but is technically precise. Overall, it earns its place 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?

Despite the tool having an output schema (which reduces the need to explain return values), the description is succinct but complete for a resolution tool with two simple parameters. It covers the 'what' and implies the 'why' in a playbook context. It lacks mention of edge cases (e.g., unresolvable skills), but for a utility tool with an output schema, it is sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description adds no additional parameter semantics beyond the schema, but given the high coverage baseline of 3, maintaining a 4 is appropriate as the parameter names and schema descriptions are self-sufficient. However, adding context like default version behavior could elevate it.

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

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

The description uses the specific verb 'Resolve' and the resource 'playbook tool_recipe.skills refs to full skill records'. It clearly distinguishes the action from siblings like memory_skill_get or memory_skills_list, but could be more precise by stating the output is a transformed playbook. Overall, it clearly communicates the core function.

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 context as part of playbook resolution, but provides no explicit guidance on when to use this tool versus alternatives like memory_playbook_get or memory_skill_get. It lacks when-not-to-use or prerequisite information. It meets minimum viability for a focused utility 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?

No annotations are provided, so the description must disclose behavioral traits. It notes that each call creates a new version and mentions a 'guarded ingestion pipeline' and visibility rules. However, it does not specify side effects (e.g., whether old versions are retained or overwritten), idempotency, or permissions needed, leaving some ambiguity.

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

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

The description is concise with four sentences, each adding value: purpose, versioning emphasis, skill definition and usage, and pipeline visibility. It is front-loaded with the main action and contains no redundant or wasted words.

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