Cachly — AI Cognitive Brain

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.10.47
Disambiguation3/5
Tools are grouped with clear prefixes (cache_, brain_, team_, global_, syndicate_), but within each group there are many tools with overlapping scopes. For example, recall_best_solution, smart_recall, team_recall, global_recall, and brain_search all retrieve knowledge with subtle differences. Detailed descriptions help but the volume forces agents to read carefully to avoid misselection.
Naming Consistency4/5
Overall naming follows a consistent snake_case verb_noun pattern with descriptive prefixes (e.g., cache_get, brain_conflicts, team_assign_role). A few tools like trace_dependency and compact_recover lack prefixes, and some use acronyms (madc_deliberate, cls_ingest), but the majority is predictable and well-organized.
Tool Count2/5
122 tools is far beyond typical MCP servers (3-15). Even for a comprehensive cognitive brain system, this number risks overwhelming agents and makes the set hard to navigate. Many tools could be consolidated (e.g., multiple session utilities, multiple recall variants with overlapping functionality).
Completeness5/5
The tool set is extremely comprehensive, covering every aspect of the declared purpose: cache CRUD and monitoring, lesson lifecycle (learn, recall, confirm, resolve, consolidate), team management, global knowledge commons, federation, session management, roadmap, and knowledge graph inspection. No obvious gaps exist for the stated domain.
Average 4.2/5 across 122 of 122 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 123 commits in the last 12 weeks
- Last stable release on August 14, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses overwrite behavior (default false) and mentions dry_run (via schema), but does not discuss permissions, rate limits, error handling, or what happens on invalid input. The description provides basic behavioral traits but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an example, front-loaded with purpose, and efficiently covers key points. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description is adequate but incomplete. It covers main functionality and two parameters, but lacks explanation of return values, error conditions, prerequisites (e.g., valid instance), and details on dry_run and min_confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining topic_prefix with an example and clarifying overwrite default, but many parameters (dry_run, min_confidence) are only described in the schema. The added semantics are helpful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports lessons from a shared snapshot into a Brain instance, specifying the input format (share ID or URL) and optional prefix. It distinguishes from siblings like brain_share (export) and brain_import_meta (likely metadata import) by focusing on lesson import, but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: import from a shared snapshot after using brain_share. It provides an example call but does not explicitly state when to use this tool versus alternatives (e.g., brain_import_meta) 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose whether the tool is read-only, has side effects, requires permissions, or triggers calls to smart_recall. The hint about passing author to smart_recall is ambiguous about this tool's own behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the main metrics, and contains no redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description explains the function and purpose adequately. However, it does not describe the return format or structure, and the smart_recall hint adds confusion about cross-tool integration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the parameter instance_id as 'UUID of the cache instance' (100% coverage). The description adds no additional semantic detail about this parameter beyond the schema, which is the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports three specific Brain metrics with brief explanations, making its purpose precise. However, it does not explicitly distinguish this tool from sibling tools like brain_discover or brain_conflicts, which could overlap in concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises when to use it ('Use to track whether the Brain is delivering its core value') and provides a usage hint about passing an author handle to smart_recall. However, it lacks explicit exclusions or alternatives to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It mentions showing typed edges and confidence scores but does not explicitly state that the tool is read-only (no mutations), nor does it discuss side effects, authentication needs, or rate limits. Score 3 for partial disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence contributes to understanding. It is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's output (typed edges, confidence scores, related concepts) but lacks details on output format, pagination, or traversal specifics. Given the absence of an output schema, the description could be more comprehensive for a knowledge graph tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 a small amount of value by giving example values for the 'concept' parameter (e.g., 'fix:clickhouse-ipv6') but does not elaborate on 'max_hops' beyond the schema or explain defaults. Score 3 for marginal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'inspect' and the resource 'Causal Knowledge Graph' for a concept. It lists the edge types shown, but does not explicitly differentiate from siblings like causal_trace or brain_search, capping the score at 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Use to understand what the brain knows about a topic and which fixes have the highest confidence.' This implies appropriate context but provides no explicit exclusions or comparisons to other tools (e.g., when to use causal_trace instead). Score 3 reflects moderate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description mentions returning lessons and recording in session history, but no disclosure of side effects, idempotency, or errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with front-loaded purpose and immediate usage context, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes inputs, output (lessons), and when to call, but lacks details on error handling, output structure, or prerequisites. Adequate for moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% means description adds limited value beyond schema; it provides source hint for changed_files but no extra meaning for required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it associates file changes with brain knowledge and returns relevant lessons. Specific verb+resource, distinguishes from siblings like brain_diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives context 'Call this after commits' but does not explicitly list when to avoid or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It describes the tool as searching and browsing, implying a read-only operation. It mentions the return content (ranked list, lesson counts, etc.) but does not explicitly state non-destructive behavior, auth requirements, or rate limits. Adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences plus an example) and front-loaded with the main purpose. Every sentence adds value without redundancy. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema), the description covers the core functionality, return types (lesson counts, topics, import commands), and provides examples. It is complete enough for an agent to use correctly, though it could be slightly more explicit about result structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds examples of usage (query and topic) and notes the output types, but does not significantly extend the meaning beyond what the schema provides. Hence baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches and browses publicly shared Brain snapshots, with specific verbs and resource. It gives examples of usage. However, it does not explicitly distinguish from sibling tools like brain_search or brain_marketplace, which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to find ready-made knowledge bases by topic or query) but does not provide explicit guidance on when not to use or mention alternatives. The examples help, but no exclusions or comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behaviors. It mentions creation but does not specify authentication needs, idempotency, return value, or potential side effects (e.g., default plan assignment).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with the core action, and efficiently covers context and follow-up without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema), the description provides adequate context: creation, follow-up steps, and plan options. Minor lack of behavioral detail (e.g., default plan) prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The description adds context about plans but does not enhance parameter semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new Cachly organization and distinguishes it from siblings like invite_member. It provides context for team collaboration and follow-up steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists follow-up actions (invite_member, upgrade plan) but does not explicitly state when to use this tool versus alternatives like list_orgs or get_org_plan. It lacks exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 tool is read-only ('Show') and returns a table, but does not disclose any behavioral traits like authentication needs, data freshness, or side effects. The description is too minimal for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and resource, no wasted words. Every sentence adds value (purpose, return format, use cases).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description covers the return format (table with handles, roles, capabilities) and provides use cases. However, it lacks details on ordering, filtering, pagination, or what 'capabilities' entails. Still reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter (instance_id) with 100% schema description coverage. The tool description does not add any additional meaning beyond the schema. Baseline of 3 is appropriate as the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and the resource 'all team members and their assigned roles on a shared brain instance'. It differentiates from sibling tools like team_assign_role (which modifies roles) implicitly, but does not explicitly distinguish itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use cases: 'Use during onboarding to see who can do what, or to verify role assignments.' Provides clear context for when to use, but no exclusions or alternatives are mentioned despite a large sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses incremental behavior and progress updates to stderr, but it does not clarify whether the tool mutates existing data, requires specific permissions, or if it is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and front-loaded with the main purpose. It could be slightly tighter but effectively communicates key points without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering the tool has 6 parameters and no output schema, the description covers purpose, incremental behavior, and progress updates. It lacks details on prerequisites (e.g., git repo access) and return value, but is otherwise complete for a bootstrap tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds context about incremental being default and the nature of parsing commits, but does not significantly enhance understanding 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bootstrap brain lessons from git history' and explains how it works (parsing commit messages, inferring fix/feature/refactor lessons). It effectively distinguishes itself from sibling brain_* tools by focusing on git history ingestion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage guidance by stating it's 'Great for onboarding an existing codebase' and mentions incremental behavior, but it does not explicitly state when not to use this tool or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions result features (badges, provenance) but lacks details on side effects, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the purpose, second provides critical details on ranking and displayed information. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the search mechanism and output features, but without an output schema, the description should more thoroughly explain return format (e.g., pagination) and domain-specific terms like 'certificate provenance'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning by explaining context_hints as 'Your tech stack' and how weighting works, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'FedBrain context-weighted search' that searches the global commons and ranks results by tech-stack similarity, distinguishing it from simpler sibling tools like brain_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (context-weighted search) but does not explicitly state when not to use or provide alternative tools for simple searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the admin-gating requirement and the effect on smart_recall visibility. However, it does not mention error handling, idempotency, or side effects such as what happens if the group does not exist. The description adds some value beyond the schema but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with the core action, then explains the behavioral effect, distinguishes from related concepts, states a precondition, and ends with a concrete example. Every sentence adds value, and there is no redundant or filler information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description covers the main purpose, effect, and precondition. However, it omits details about error cases, return values, and default behavior for the action parameter. The example helps but does not address all potential uncertainties an agent might face.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 reinforces the meaning of assigned_by by stating that the user must be admin, and explains the group concept. It provides an example mapping parameters to values. However, it does not significantly add new semantic information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb (add or remove) and resource (team member to/from a named group on a shared brain). It explains the behavioral effect of group-scoped lessons on smart_recall, distinguishing this from other visibility concepts. The purpose is specific and unambiguous, making it easy for an agent to understand what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context: it mentions that this is orthogonal to lesson-level private and that it is admin-gated after bootstrap. However, it does not explicitly contrast with sibling tools like team_assign_role or team_scopes, nor does it specify when to use this tool versus alternatives. The usage guidance is implied but not explicitly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently describes the output structure and schema, but does not disclose behavioral traits such as whether the operation is read-only, required permissions, or side effects on the brain graph. The agent cannot assess safety from the description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient, with two information-rich sentences and a line of examples. Every sentence adds value: purpose, schema details, and example usage. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output structure (nodes, links, attributes) and format options (json/summary) thoroughly, compensating for the lack of an output schema. However, it omits details like error handling, performance characteristics, or constraints beyond max_nodes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all five parameters have descriptions). The description adds marginal value with example invocations and clarifies defaults like max_nodes=400, but does not substantially enhance understanding beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports a Causal Knowledge Graph as a 3D-render-ready payload, specifying the schema, node/link attributes, and target frontends. It is a specific verb-resource combination that distinguishes it from siblings like ckg_inspect or brain_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for obtaining a renderable graph but does not explicitly state when to use this tool over alternatives (e.g., ckg_inspect) nor when not to use it. The context of 'data layer behind the brain viz' is clear but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that preferences are stored in Redis and survive restarts, which is adequate for a simple set operation. However, it does not mention overwrite behavior, error conditions, or whether the operation is synchronous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the core purpose. Every sentence adds value—purpose, storage, and a concrete example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description is mostly complete. It covers the purpose, storage, and a known key. It could briefly mention the return value (e.g., success indicator) but is not critically missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 by explaining the concept of 'user preference' and providing context for the auto_changelog key, but it does not introduce new constraints or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'persist' and resource 'user preference' for a Brain instance. It distinguishes from siblings like brain_get_pref (get) and cache_set (generic cache) by specifying that it's a user preference and giving a concrete example (auto_changelog).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for setting persistent user preferences with examples, but it does not explicitly state when to use this tool versus alternatives (e.g., brain_get_pref, cache_set) or provide exclusions. The context is clear but not directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the core behavior: export, create link, return URL and import command. It mentions optional filtering and visibility. However, it does not state whether the operation is destructive, idempotent, or has side effects (e.g., does it modify the original brain? Does it create a new share each time?). No mention of permissions or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long plus an example, all front-loaded with the core action. Every sentence adds value: the first explains the main operation, the second covers optional filtering and visibility, the third describes the return value. The example demonstrates usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no output schema, and no annotations, the description covers the main functionality (export, share link, return value, filtering, visibility). It explains the return value (share URL and import command), which is important since there is no output schema. However, it does not mention the dry_run or max_lessons parameters, which are part of the schema. The example helps but does not fully compensate for these omissions. Still, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 an example (brain_share(instance_id="...", title="My Auth Patterns", topic_filter=["auth"])) but does not provide additional meaning beyond what the schema already gives for each parameter. It does not explain dry_run or max_lessons in the description text. The schema already covers the parameter semantics adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Export a Brain snapshot and create a publicly shareable link'. It specifies the resource (Brain snapshot), the verb (export/create), and the outcome (shareable link). This distinguishes it from siblings like brain_import (import) or brain_share_list (list shares), though it does not explicitly contrast them. The purpose is unmistakable and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to share a brain snapshot), but does not explicitly state when not to use it or how it differs from alternatives like brain_share_list or brain_unshare. No exclusions or alternatives are mentioned. The context is clear enough for an agent to infer basic usage, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 mentions checking the local provenance log and the cachly API, which hints at multi-source behavior. However, it does not disclose side effects, authentication needs, rate limits, or whether it is safe to call repeatedly. The read-only nature is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an example, all front-loaded. The first sentence states the purpose, the second lists the output fields, the third mentions data sources, and the example shows exact usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description effectively lists the returned fields and the data sources. It covers the essential information for an agent to use the tool. Missing details are minor (e.g., pagination, error handling, empty results).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter 'instance_id' is described in the schema as 'UUID of the Brain instance that created the shares'). The description adds an example call but no additional semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'Brain snapshots you have previously shared', and specifies the returned fields (share ID, title, lesson count, visibility, creation date). It distinguishes from sibling tools like brain_share (create) and brain_unshare (delete) by naming the specific action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to list shares) but does not explicitly state when to use this tool versus alternatives, nor does it provide prerequisites or exclusions. The example gives a usage pattern but no comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states it returns data, but does not disclose if it's read-only, requires authentication, or any other behavioral traits. Lacks safety or side-effect context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Purpose front-loaded in first sentence. Efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers return fields adequately. Could be improved by mentioning if results are paginated or unlimited, but not critical for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters with 100% coverage, so description adds value by explaining what fields are returned (plan, seat count, member info). Baseline of 4 for 0 parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'List' and resource 'Cachly organizations'. Distinguishes from sibling tools like 'create_org' and 'get_org_plan' by focusing on listing all orgs with plan/seat/member info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for viewing all organizations, but lacks explicit when-to-use, when-not-to-use, or alternatives. No exclusions or comparisons to related tools like 'get_org_plan'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses key behaviors: compresses 30-50 sessions, groups by category, creates persistent crystals (survive cleanup), and returns a digest. However, it does not explicitly state whether the operation is read-only or modifies existing sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loads the main action, and contains no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the tool's purpose, output (digest), and usage context. It could mention error conditions or limits on crystal count, but overall provides sufficient context for an agent to understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the label parameter with examples and auto-generation behavior, but does not add meaningful detail for instance_id beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool compresses recent sessions and learned lessons into a Memory Crystal, grouped by category. It distinguishes itself from siblings by noting that crystals survive session cleanup and appear in session_start, but does not explicitly differentiate from similar tools like memory_consolidate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Run this monthly or after a big milestone to preserve institutional knowledge.' However, it does not mention when not to use the tool or suggest alternatives, leaving the agent to infer exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the core behavior (listing pairs based on file events or recalls, flagging solo contributors) and mentions output details (routing suggestion, example). However, it lacks disclosure about error handling, performance, or side effects. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise, front-loaded with the main purpose, and includes a helpful example. A few sentences could be tightened (e.g., the example could be more compact), but overall it is efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description covers the key aspects: what data is shown, how collaboration is detected, use cases, and an example. It does not specify the exact return format (e.g., list of objects), but the example provides sufficient guidance. Minor gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented in the schema. The description does not add meaning beyond what the schema provides (e.g., default of min_weight is stated but already in schema). Baseline 3 is appropriate as the description adds no extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows a 'Person↔Person Collaboration Graph' listing pairs of contributors who collaborated via file touches or smart_recall, with routing suggestions and bus-factor analysis. This distinctively differentiates it from sibling tools like brain_who_knows or brain_file_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies ideal use cases (onboarding, bus-factor analysis) and provides an example call, but does not explicitly exclude misuse or compare with alternative tools. The context is clear enough that an agent would use this for collaboration networks rather than other brain_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: imported lessons get state='meta', never overwrite local lessons, and are k-anonymous. This goes well beyond the input schema. However, it omits details like authentication requirements or what happens on failure, preventing a top score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the primary action, no filler. Every sentence adds essential information about purpose, data origin, behavior, and optional filtering. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, and filtering but lacks information about the return value (no output schema) and prerequisites (e.g., must have a local Brain instance). Given the tool's simplicity (3 params, no nesting), it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds only a brief usage hint ('Filter by category to target relevant patterns') for the category parameter, which provides marginal value 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Import k-anonymous meta-lessons from the global Brain commons into your local Brain'—a specific verb+resource. It explains what meta-lessons are and distinguishes from potential siblings like brain_import by noting they are derived from k independent org signals and never overwrite local lessons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the action and filter hint ('Filter by category to target relevant patterns'), but it does not explicitly state when to use this tool over alternatives (e.g., brain_import, brain_share) or when not to use it. No exclusions or context for decision-making are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description must cover behavioral traits. It only mentions search scope and usage, but omits aspects like read-only nature, pagination, rate limits, or any side effects. The agent lacks key behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states purpose and scope, the second gives usage guidance. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain return format or limitations. It only covers usage and scope, leaving gaps for a search tool. However, it does differentiate from a key sibling, so it is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with standard param descriptions. The tool description does not add significant new meaning beyond what the schema already provides (e.g., query is 'What to search for'). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs BM25+ full-text search over all brain data types (lessons, context entries, session history, CKG nodes, roadmap items). It uses a specific verb and resource, and contrasts with smart_recall to differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when smart_recall returns nothing or when wanting to find anything the brain knows. Provides clear context for when to choose this tool over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that lessons are tagged source:'starter', never override existing lessons, and are idempotent. However, it omits details about potential side effects (e.g., database writes, permission requirements, or performance impact), leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of 4 sentences, front-loaded with the core action and followed by usage context, properties, and an example. It is efficient but could be trimmed slightly (e.g., 'universal, high-value' is slightly verbose). Still well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (1 required), no output schema, and no annotations, the description covers the tool's purpose, usage context, idempotency, tagging behavior, and example calls. The connection to smart_recall is explained. It is complete enough for an agent to decide when and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 4 parameters have descriptions). The description adds value by showing example invocations and explaining topic_filter in context, but the schema already defines each parameter adequately. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description defines a specific verb (seed) and resource (Brain) with clear content (curated engineering lessons). It distinguishes from siblings by referencing smart_recall and positioning itself for fresh setups, avoiding overlap with tools like brain_import or brain_discover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context ('ideal right after setup or in a fresh repo') and idempotency guarantees, but does not mention when not to use the tool or name alternative siblings beyond smart_recall. The usage is clear but lacks exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explains that ingestion happens without session_end calls and lists each source's data fields. However, it lacks details on side effects, idempotency, error handling, or whether it is destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat verbose and could be more concise. While front-loaded with core purpose, it includes redundant phrases like 'install automatic ingestion' and 'brain learns from every commit' that could be streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three required parameters and no output schema, the description covers the purpose and source details adequately. However, it lacks information on return values, error conditions, or success indicators, leaving gaps for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all parameters and nested objects (100% coverage). The description adds contextual meaning by elaborating on each source type and its data structure, which helps the agent understand usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: ingesting learning signals from specific sources (git_commit, ci_outcome, ide_diagnostic) without requiring explicit session_end calls. It distinguishes from siblings by mentioning automatic ingestion and hook installation, and ties into the broader system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to ingest learning signals from the listed sources) and hints at prerequisites (install hooks via cls_install_hooks). However, it does not explicitly state when not to use it or compare with alternatives like session_end.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides good behavioral details: it creates a certificate, requires 10+ confirmations for Gold Standard, and uses context-weighting for ranking. However, it does not disclose authorization needs, reversibility, or 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words. It front-loads the main purpose and efficiently conveys key behavioral aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains purpose and behavior, but with no output schema, it fails to mention what the function returns. It also omits prerequisites, error conditions, and any cost or rate limits, making it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 about lesson contribution and certificate but does not add significant meaning beyond the schema's parameter descriptions (e.g., instance_id, lesson_key, visibility).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Contribute a lesson') and resource ('global Knowledge Commons'), and distinguishes it from siblings by mentioning cryptographic certificate, 10+ confirmations for Gold Standard, and context-weighting for search ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for contributing lessons and mentions context-weighting, but does not explicitly state when to use this tool over siblings like fedbrain_confirm or fedbrain_search, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the voting process, the effects of unanimous and split decisions, and the permanent storage of resolutions. However, it does not mention idempotency, rate limits, or authentication needs, which would strengthen transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that includes both high-level purpose and granular details about voting rules. It is moderately concise but could be split into clearer sections (use case, behavior, output) without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the deliberation process well, but it omits what the tool returns (since no output schema is present). It implies manual invocation is possible but focuses on automatic use. For a complex tool, this leaves some ambiguity about expected responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description does not add semantic details beyond the schema, such as acceptable formats for the topic or how context influences deliberation. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: resolving conflicting lessons through multi-agent deliberation. It names the six specialist agents and specifies outcomes (unanimous vs. split vote), and distinguishes itself from siblings by referencing automatic invocation from learn_from_attempts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use the tool—when conflicting lessons exist—and notes that it is called automatically by learn_from_attempts. It mentions causal_trace as a follow-up for split votes, providing context, though it does not explicitly list alternatives 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the fallback behavior to remember_context keys and shows a return example, which is valuable. However, it doesn't explicitly state read-only semantics, result cardinality, or any potential side effects, leaving some ambiguity for a tool with no annotation 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the main purpose, a contrast with exact matching, a concrete example, and a fallback note. Every sentence earns its place with no redundancy or vague filler. The information is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should clarify return semantics. It gives one example ('returns cached auth architecture summary') but doesn't specify whether the return is a single result, a list, or how results are structured. For a 5-parameter tool with no output schema, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides detailed explanations for all 5 parameters (e.g., threshold, author, context_files). The description adds no additional parameter semantics beyond the example query, which doesn't elaborate on parameter syntax or interactions. The baseline of 3 is appropriate given the schema's thoroughness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Semantically search cached context using natural language' and provides a concrete example ('how does authentication work' → returns cached auth architecture summary). It explicitly contrasts with exact key matching, distinguishing it from sibling cache retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Instead of exact key matching' gives clear context on when to use this tool versus exact lookup alternatives. The fallback note ('Falls back to remember_context keys') adds useful behavioral context, though it doesn't explicitly name sibling tools like semantic_search or recall_context for direct comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the sorting logic, time window, and minimum confirms, which is adequate. However, it does not mention rate limits, whether it is a read-only operation, or if results are computed dynamically vs cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding unique value: purpose + metric, usage guidance, and a threshold condition. No redundant information, front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what is shown but does not specify the fields returned or ordering details beyond the metric. The limit parameter is covered, but for a trending list, more details on output format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (limit) with a schema description that covers default and max. Schema coverage is 100%, so baseline is 3. The description adds no additional parameter semantics beyond the schema, but the main text provides context about the tool's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show', the resource 'trending lessons', and the specific metric 'confirmation velocity' with a time window, effectively distinguishing it from siblings like syndicate and syndicate_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use this at the start of a session or weekly review to see what the community is actively validating.' It also mentions a condition (at least 2 confirms), but does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden. It explains the ranking effect, badge, and senior vs peer weight, but does not cover reversibility, idempotency, permissions, or the immediate return result. This leaves gaps for a full behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, no redundancy. Every sentence earns its place by explaining effect, usage, or parameter behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and effect on recall, but lacks information about return values, success/failure indicators, or prerequisites. Given no output schema, the description should at least hint at the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the nuance that 'distinct endorsements add a small boost' for the 'level' parameter, which is not in schema. No other parameters gain new meaning, so the added value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (endorse/confirm) and resource (team lesson), and distinguishes it from auto-learned entries. It explains the ranking effect and badge, which sets it apart from other tools like brain_confirm_ci or recall tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends use in 'code review or knowledge reviews' and describes the outcome (higher ranking, badge). It does not list when not to use or name alternatives directly, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that mark_review can cause side effects and explains dependency storage, but lacks details on error handling, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with front-loaded purpose. No fluff; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description explains purpose and side-effect parameter but omits return value format. Without output schema, this is a gap. Adequate for basic use but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. Description adds marginal context (example dependency pattern, default for mark_review) but does not significantly extend beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'find all lessons that depend on a given prerequisite' and provides a concrete example. The tool name 'trace_dependency' aligns well. No sibling with identical function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'When a dependency changes...call this'. Context is clear but does not mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 it checks health and returns issues, suggesting a read-only operation. However, it does not disclose potential side effects (e.g., if it modifies state), required permissions, or any limitations. The description is minimally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence states the core purpose, and the second lists specifics and output format. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return value (prioritized list of issues with fix instructions). Parameters are covered. It lacks mention of whether the tool can be called repeatedly or any performance implications, but overall is complete for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are well-documented. The description adds value by explaining that workspace_path enables package.json analysis for openclaw cross-promo, exceeding the schema description. Baseline 3 plus extra context justifies 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources ('Check the health', 'reports', 'returns prioritized list') and clearly differentiates from sibling tools like brain_diff or brain_predict by focusing on health diagnostics and actionable recommendations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and what it returns (issues with fix instructions), but does not explicitly state when to use it versus alternatives or when not to use it. Use cases are implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It correctly states the return value on cache miss (null) and the storage key format, but omits details like read-only nature, error conditions, or performance characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two lean sentences with no wasted words. The action verb and outcome are front-loaded, making it easy for an agent to quickly grasp the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return value and its structure (ordered list of string chunks, null on miss). It covers the main use case but could mention potential error scenarios beyond cache miss.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (100%). The description adds value by revealing the key format ('cachly:stream:{key}'), which helps the agent form correct key values beyond the schema's generic 'Cache key' description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Retrieve' and the resource 'previously cached stream as an ordered list of string chunks'. It distinctly separates this from sibling cache tools like cache_get (single value) and cache_stream_set (write operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is used for reading a stream of chunks, but does not explicitly state when to use it versus alternatives like cache_get or cache_mget. No exclusion criteria or use-case guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes full responsibility for behavioral disclosure. It details the sources used (Memory Crystal, recent sessions, WIP registry, open failures) and the outcome (condensed briefing, no lost progress). This gives an agent meaningful transparency about inputs and effects, though potential side effects (e.g., if it mutates state) are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. It front-loads the critical usage instruction ('Call FIRST...') and follows with concise explanation of behavior and result. Every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, no output schema, and no annotations, the description covers the core behavior, usage scenario, and output. It does not explain domain-specific terms (Memory Crystal, WIP registry) or potential side effects, but for an agent in this domain, it likely provides sufficient context to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter schema has 100% description coverage, with instance_id and focus clearly documented. The tool description reinforces the focus parameter's purpose ('helps filter relevant context'), but adds no new semantic value beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to reconstruct full context after a context limit hit or compaction. It uses a specific verb ('reconstructs') and identifies the resource ('full context'). However, it does not explicitly differentiate from siblings like memory_consolidate or recall_context, which may have overlapping roles, though the 'FIRST' instruction provides implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Call FIRST after any context limit hit / compaction.' This clearly indicates the condition and priority. It does not list alternatives or when not to use, but the strong directive is adequate for an agent to understand when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 implies a read-only operation ('Show your... status'), but does not explicitly state that it is non-destructive, requires any permissions, or has performance implications. While adequate for a simple status check, more explicit safety guarantees 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence lists the tool's function and bullet-point style items, followed by a single sentence on usage. Every part adds value, and the key action is front-loaded. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description enumerates the return items (lessons contributed, recent confirmations, etc.), providing a good mental model of the output. It does not detail data format or caching behavior, but for a status tool with a single parameter, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the single parameter 'instance_id' is already described as 'Brain instance ID' in the schema. The description adds no additional semantic context beyond what the schema provides, warranting a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb 'Show' and a specific resource 'FedBrain federation status'. It lists concrete items (lessons contributed, recent confirmations, etc.) that differentiate it from siblings like fedbrain_confirm and fedbrain_contribute, which perform actions rather than display status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Use to track your brain's global knowledge contribution,' providing clear usage context. However, it does not explicitly exclude cases when not to use it or mention alternatives, though the sibling tools for specific actions imply when a more targeted tool might be needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 the destructive nature (delete) and supports glob patterns. However, it does not describe behavior on missing keys, authorization needs, or reversibility. The transparency is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and no extraneous information. Every sentence is earned and succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required parameters, no output schema, no nested objects), the description covers the essential information. It could mention return value or error states, but it is complete enough for a basic delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The tool description does not add any new semantic information beyond what is in the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes one or more cached context entries, which is a specific verb+resource combination. It distinguishes from sibling tools like cache_delete by specifying 'cached context entries' rather than generic cache.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use when context is stale or you want to force a fresh analysis.' It also gives an example of glob pattern usage. However, it does not mention when not to use or list alternatives, but the guidance is clear and context-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It accurately discloses the tool's read-only nature (retrieving a string) and implies a prerequisite ('running instance'). However, it does not explicitly state it has no side effects or mention potential errors (e.g., instance not found), which would elevate the score further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences that front-load the purpose and usage context. Every phrase adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is sufficiently complete. It explains what the tool returns, the protocol, and a typical use case. Minor improvement would be to mention the exact return format (string) and potential errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage on the single parameter, including a description ('UUID of the instance'). The tool description adds no additional semantic detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a Redis/Valkey connection string for a running instance, specifying the protocol (redis:// URL). This is a specific verb-resource pair that differentiates it from sibling tools like cache operations or session management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('configure your application or set environment variables') but does not explicitly state when not to use it or mention alternative tools. Since no sibling tools serve a similar purpose, this is adequate minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It mentions persistence ('survive across sessions') and up-to-dateness, which are helpful. However, it does not disclose any potential side effects, permission requirements, or data validation behaviors beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two core sentences plus one sentence referencing siblings. It front-loads the purpose and avoids superfluous words, with every sentence adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema), the description explains persistence, usage scope, and mentions sibling tools. It lacks details on validation constraints or required permissions, but it covers the essential aspects for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 6 parameters with descriptions, achieving 100% coverage. The tool description does not add extra meaning beyond what the schema already provides, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'new item to the persistent project roadmap stored in the Brain'. It differentiates from siblings by referencing roadmap_list and roadmap_next, specifying its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use for features, bugs, refactors, or any planned work.' It also references sibling tools for alternative actions (listing and next item), providing 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that results are sorted by priority then creation date, and that it is called automatically, which adds value beyond the schema. However, with no annotations provided, it fails to explicitly confirm read-only behavior, mention any side effects, or note rate limits or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long, front-loaded with the primary purpose, and every sentence provides essential information without redundancy. It is highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's behavior (filtering, sorting, automatic invocation) given the absence of an output schema and the moderate complexity. It could be improved by mentioning the return format or pagination, but it is largely sufficient for selecting and using the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully described in the input schema (100% coverage), so the description adds minimal new semantic information. It reiterates the filters but does not clarify parameter values beyond what the schema already provides, though it mentions the default status 'open' which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('List all roadmap items') and explicitly mentions the optional filters (status, priority, tag, milestone). It clearly distinguishes from sibling tools like roadmap_add and roadmap_update by focusing on listing versus creating or modifying items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is 'Called automatically by session_start to show open work,' providing clear context for when it is used. However, it does not explicitly mention when not to use it or suggest alternatives like roadmap_next for single-item retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It lists the many returned items and mentions saving a session start marker and reconstructing from git log. However, it does not discuss side effects like potential state resets, performance impact of the large return, or error handling. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the key purpose. It lists return items in a readable format without unnecessary verbosity. Minor improvements could be made with bullet points, but it is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple return items, side effects, 5 parameters, no output schema), the description covers the main functionality and return values. However, it lacks details on expected behavior for invalid inputs (e.g., missing instance_id) or failure modes. Adequate for core use but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have descriptions in the schema (100% coverage). The description adds valuable context beyond the schema, such as how 'focus' surfaces relevant lessons, 'author' enables team telepathy, and 'workspace_path' triggers git log reconstruction. This enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'Single-call session briefing' to be called at session start, explicitly distinguishing it from sibling tools like smart_recall and recall_best_solution. The verb 'call' and resource 'session start' 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to call ('at the START of every session') and what to use instead ('INSTEAD of multiple separate smart_recall/recall_best_solution calls'). It also mentions the marker for session_end. While clear, it could include guidance on when not to use this tool (e.g., for single queries).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that results are ranked by confirm_count then recency and provides an example output format. While it doesn't cover rate limits or auth, the behavioral traits of a search tool are well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a purpose statement, usage advice, and an example. It is relatively concise for the information conveyed, though the example could be separated for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers tool purpose, ranking, and usage, but lacks explicit details about the full return structure (e.g., whether it returns a list of objects with specific fields). The example hints at the format but is not exhaustive, which is a gap given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited extra value. It mentions that leaving q empty returns most recent lessons and gives a category prefix hint, but these are minor enhancements to already clear schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as searching the 'GLOBAL Cachly Knowledge Commons' for community solutions, distinguishing it from siblings like brain_search and fedbrain_search by emphasizing the global scope and community contributions. The specific verb 'search' and resource noun phrase make the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool 'BEFORE debugging any unknown issue', providing a clear use case. However, it does not list any conditions when to avoid it or name alternative tools for comparison, which would strengthen the guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions output fields (author, recency, severity) but does not explicitly state it is read-only, nor does it discuss authentication, rate limits, or side effects. The read-only nature is implied but not guaranteed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the main action, no redundant words, and ends with a clear use case. Perfectly sized for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what the tool returns (author, recency, severity). It covers key use cases and scope but lacks detail on pagination or default behavior for limit. Overall sufficient for a simple recall tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds context beyond schema by explaining how parameters are used (e.g., 'find who knows about a topic' for topic, 'showing who learned what' links to author). It also mentions output fields not in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool recalls lessons from a shared team brain, specifying the action and resource. It distinguishes from siblings like global_recall or smart_recall by focusing on a specific instance_id for team learning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use this to onboard new team members or find who knows about a topic.' It also explains it works on any shared instance, but does not compare with alternative recall tools or mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the read-like behavior ('List...') and the conditional behavior based on 'handle'. However, it does not mention authorization requirements, rate limits, whether the operation is idempotent, or what happens if the instance is invalid. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each providing distinct value: the first defines the tool's action, the second explains parameter usage, the third suggests a practical use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is relatively simple (2 params, no output schema, no nested objects), the description covers the core behavior well. It explains both parameter modes and offers a concrete use case. It could mention pagination or expected output format, but for a list tool without output schema, this is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds minimal value beyond the schema. The description explains the role of the 'handle' parameter (filtering to one person's memberships) which is slightly richer than the schema's terse 'Optional — show only this person's group memberships'. However, for 'instance_id', the description adds nothing 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and nouns: 'List team groups and their members, or the groups a specific person belongs to.' It also clarifies the dual behavior based on presence of the 'handle' parameter and distinguishes itself from sibling tools like 'team_roster' or 'team_assign_role' by focusing on scope membership auditing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to pass the optional handle ('to see one person's scopes') and when to omit it ('to see all groups on the instance'). It also suggests a use case: 'Use to audit who can see group-scoped lessons.' However, it does not explicitly mention when NOT to use this tool or provide alternatives among the many sibling tools (e.g., team_audit, team_recall).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states the tool is idempotent and non-destructive, never overrides existing lessons, and can be re-run for updates. It also mentions offline functionality. This covers key behavioral traits, though it omits potential side effects or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 5 sentences, with the main action front-loaded. It is reasonably concise, but the first sentence is somewhat long. Every sentence adds value, and the structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema or annotations, the description covers the purpose, safe usage, and an example. It lacks details on the return format (beyond the example string) and potential side effects, but overall it is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 5 parameters fully (100% coverage). The description adds minimal value beyond the schema—it provides an example (slug only) and implies default behaviors (e.g., limit default 200) but does not explicitly detail defaults or the meaning of instance_id, dry_run, min_confirms. The example omits the required instance_id, which is a minor inconsistency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool installs a Domain Brain, pulling curated lessons for immediate use. It distinguishes from sibling tools like brain_marketplace (browse) and brain_search (search) by specifying the action and the result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells users to browse available brains first with brain_marketplace() and gives an example of usage. It also mentions it can be re-run for updates, implying idempotent usage. However, it does not explicitly contrast with other install-like tools (e.g., brain_import) or state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses key behaviors: installation of a hook, idempotence, use of curl, exit 0, asynchronous execution, and return values. However, it omits potential side effects like file modification (hook script), error handling, or internet connectivity requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that effectively front-loads the core purpose. Each sentence adds necessary information without redundancy. It is concise but could be slightly more structured (e.g., bullet points for key traits).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explicitly states the return value (hook path and installation status). It covers the main workflow, safety, and environment requirements. Missing details include error scenarios, prerequisites (git installed), and behavior if the directory is not a git repo, but overall it is fairly complete for an installation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented. The description adds minimal extra meaning beyond restating what the schema covers (e.g., api_key for authentication, instance_id for target brain). Baseline 3 is appropriate as the schema carries the primary burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it installs a git post-commit hook to automatically learn from every commit, with a specific verb and resource. It explicitly distinguishes from the sibling tool 'brain_from_git' by saying 'no manual brain_from_git needed'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (as a replacement for manual brain_from_git) and provides context like idempotency, compatibility (curl, any environment), and non-blocking behavior. It does not explicitly list when not to use or alternatives, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it uses SCAN (non-blocking), supports optional pattern, and returns at most count keys. Without annotations, it provides good behavioral context, though it omits details on potential duplicates or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the purpose, behavior, and constraints. The first sentence front-loads the core action, and every word adds necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should hint at what is returned (e.g., an array of key strings). It covers input and behavior well but lacks return format, leaving a gap for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema by providing example glob patterns for 'pattern' and explaining the 'count' parameter with defaults and max. However, 'instance_id' lacks description in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List' and the resource 'keys in a cache instance', and provides example glob patterns. This distinguishes it from sibling tools like cache_get or cache_set, which deal with individual key values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description mentions using SCAN to avoid blocking, it does not explicitly state when to use this tool vs alternatives (e.g., cache_mget for specific keys). Usage context is implied but not contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behavioral details: atomic Lua script, fencing token matching, and conditional deletion. However, it does not describe what happens on failure (e.g., token mismatch).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, and front-loaded with the main action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not explain the return value (e.g., success indicator). For a release operation, knowing if the release succeeded is important context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by linking 'key' to cache_lock_acquire and explaining 'token' as the fencing token, which clarifies relationships beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it releases a distributed lock and distinguishes from sibling tools like cache_lock_acquire by specifying the atomic release mechanism and fencing token check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after acquiring a lock but provides no explicit guidance on when not to use it or alternatives. The context of sibling tools (cache_lock_acquire) helps, but direct advice is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains return order and null handling for missing keys, which is valuable. However, it omits potential side effects or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding distinct value: one for purpose/mechanism, one for return behavior. No redundant or superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with 2 required parameters. Description adequately covers purpose, behavior, and return characteristics. No output schema needed given clarity of return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The tool description adds no additional meaning beyond what the schema provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action (retrieve multiple keys), mechanism (native Redis MGET), and distinguishes from sibling tools like cache_get (single key) and cache_mset (set multiple).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description mentions efficiency ('one round-trip') but does not explicitly state when to use this vs alternatives (e.g., individual cache_get calls). Usage context is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses the scanning pattern ('keys under org:{org_id}:sem:*'), the Cachly API aggregation, and states 'Zero-config: no API changes required'. It implies read-only behavior but does not explicitly confirm non-destructiveness. Still, behavioral coverage is good.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 4-5 sentences, front-loaded with the main purpose, and each sentence adds value. Slightly verbose but not wasteful; could be tightened but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description lists return elements (shared entries count, hit metrics, savings, per-instance breakdown). It covers the tool's purpose and data sufficiently for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). The description adds context for org_id by showing the key pattern, but provides no extra detail for instance_id. Given high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and resource ('shared cache statistics for an org namespace'), and clearly differentiates from sibling tools like cache_stats by focusing on org-level shared cache. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are provided: 'Use this to verify org-sharing is working and to monitor cross-instance cache utilization.' While no 'when not to' or alternative tools are mentioned, the context is clear enough for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: computes embeddings, checks similarity ≥ 0.98, writes to Valkey and pgvector index, and requires an API key. It does not mention what happens when a similar entry exists (likely skipped), nor return values or error conditions, but the core process is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, each providing distinct information: what it does, the algorithmic steps, typical use cases, and a prerequisite. There is no fluff or repetition; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's core functionality but omits several aspects: no output schema or return value description, no mention of idempotency or handling of duplicate entries, no prerequisites beyond API key, and no comparison with sibling cache tools. For a tool with no output schema and moderate complexity, these gaps reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so each parameter already has a description. The tool description adds context by explaining how parameters like entries and namespace are used in the process (e.g., per-entry namespace override, auto-namespace). This adds some value beyond schema, but not significantly; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Pre-warm the semantic cache') and specifies the resource ('list of prompt/value pairs'). It details the internal process (computes embedding, checks similarity, writes to Valkey + pgvector), which leaves no ambiguity about the tool's function. It also distinguishes itself from sibling cache tools by focusing on bulk pre-warming with similarity checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are given: 'seed FAQ responses, product descriptions, or known-good LLM answers before the first real user traffic.' The description also notes the requirement for OPENAI_API_KEY. However, it does not directly contrast with sibling tools like cache_set or cache_mset for single-item caching, which would help an agent decide between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 tool returns billing info and a portal URL for upgrades, implying read-only behavior. However, it does not specify authentication requirements, error handling (e.g., missing org), or rate limits, leaving gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences without redundancy. The first sentence lists the tool's output, and the second provides a next-step action. Every sentence earns its place, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is sufficient. It explains what the tool does, what it returns (plan name, price, seats, billing date), and what action to take (use billing portal URL). No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (org_id) is fully described in the schema as 'UUID of the organization' with 100% coverage. The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'get the current org plan, seat usage, and billing info' with specific items (plan name, price, seats used/max, next billing date). This is a specific verb+resource and distinguishes itself from sibling tools, none of which cover billing/plan info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear usage hint: 'To upgrade: use the billing portal URL returned by this tool.' However, it lacks explicit exclusions or when-not-to-use guidance. Since sibling tools are distinct, no direct alternatives are mentioned, but the hint provides actionable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: recursive directory walk, file reading, storage format (summary + path), requirement for embedding provider, and TTL. No annotations provided, so description carries full burden. Lacks detail on error handling or file size limits, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured, front-loaded with purpose. Four sentences efficiently cover purpose, behavior, prerequisites, and re-run guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, description covers main aspects but lacks details on return format, error handling, and edge cases (e.g., symlinks, large files). Adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds minor context like default values for extensions and max_files, but largely repeats schema info. Does not provide additional semantics beyond what schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool indexes local source files into a semantic cache for AI assistant use, specifying the verb (index), resource (source files), and purpose (enable semantic search). Distinguishes from sibling tools like semantic_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (initial setup, after major refactors) and prerequisites (embedding provider). Does not explicitly state when not to use, but context is clear enough. Could mention alternatives but not necessary given sibling diversity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so full burden on description. It discloses that notes are appended, but does not mention persistence, authorization, or error conditions (e.g., invalid item ID). Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with verb and resource, every sentence earns its place. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main actions and lifecycle, but with 7 parameters and no output schema, it omits details on optional parameter behavior (e.g., partial updates) and potential errors. Adequate for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining the lifecycle context for the status parameter. Other parameters are well-described in schema; description does not add much beyond.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the status, priority, or details of a roadmap item' and specifies the lifecycle transitions (planned → in-progress → done/blocked/cancelled). It effectively distinguishes from siblings like roadmap_add and roadmap_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: moving items through lifecycle and adding notes. However, lacks explicit when-not-to-use or comparison with alternative tools (e.g., roadmap_next).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 setting this cost affects cache_stats output and mentions a default. However, it does not state whether the change is persistent, whether it overwrites previous values, or what happens if the instance doesn't exist. Given the simple nature of the tool, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each earning its place: purpose, usage context, default, examples, consequence, prerequisite. Front-loaded with the core action and immediately useful. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 required params, no nested objects) and no output schema, the description covers the input well but omits what the tool returns (e.g., success confirmation). It implies success via 'After updating, cache_stats will show...' but does not state return value. For a simple setter, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both parameters have descriptions). The description adds significant value beyond the schema: default cost value, mapping model names to example costs, and linking to list_instances for instance_id. This extra context justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Set' and resource 'assumed cost per avoided LLM API call' for a specific instance. It explains the purpose (accurate ROI savings in cache_stats) and provides concrete examples, distinguishing it from sibling tools like cache_set or cache_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides context for when to use: to set actual model cost for accurate numbers, with examples. Recommends using list_instances first to find instance_id. Does not explicitly state when NOT to use or compare to alternatives, but the narrow scope makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses key behaviors: returns content, optionally writes to project directory, and uses embed provider. However, it omits error handling, prerequisites (e.g., instance validity), and side effects beyond file writing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with layers and front-loads the main purpose. It is slightly lengthy but every sentence adds value without fluff. Could be tightened for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3-layer system), schema coverage (100%), and no output schema, the description covers purpose, return value, and optional behavior. Lacks details on error handling and prerequisites, but is reasonably complete for a setup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline of 3. The description adds useful context like default embed provider and local setup hint, and clarifies optional writing behavior. This adds value beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a one-shot setup of a 3-layer AI memory system, listing each layer's components and its outcome. It distinguishes itself from sibling tools that perform individual memory operations (e.g., learn_from_attempts, smart_recall).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for initial project setup but provides no explicit guidance on when to use this tool versus alternatives like individual memory tools. No 'when not to use' or specific contexts are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 describes the output behavior (grouped Markdown with author, recall count, confidence) and the input parameters. However, it does not explicitly state side effects (e.g., whether the tool is read-only, modifies state, or has rate limits). The description is sufficient for understanding the tool's behavior but lacks explicit safety or idempotency assurances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three sentences and an example. The first sentence states the primary action and resource, the second adds key output details, and the third provides use cases and an example. Every sentence adds value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description covers the essential aspects: what it does, output format (Markdown grouped by topic with annotations), and usage context. It lacks mention of edge cases (e.g., empty results) or error handling, but for a changelog generation tool this is adequate. The example further clarifies invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaning beyond the schema by explaining the overall output (grouped changelog with annotations) and provides an example that contextualizes the parameters (instance_id and days). This helps users understand how parameters affect the result, particularly the grouping and annotation features not detailed in individual schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Generate a human-readable Markdown changelog of lessons learned in the last N days.' It specifies the resource (lessons), the action (generate changelog), and the output format. This is distinct from sibling tools like brain_conflicts, brain_doctor, or brain_briefing, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends use cases: 'Ideal for weekly standups, sprint retros, or async team updates — share the output directly in Slack or a doc.' While it doesn't name alternatives or specify when not to use the tool, the context provides clear guidance on appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 clearly states the tool is read-only (reports a score), provides an example output format, and implies no destructive side effects. This is sufficient behavioral transparency for a non-mutating diagnostic tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, report contents, usage guidance, alternative tool, example output. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a simple input schema (no nested objects, no output schema), the description is comprehensive enough. It covers purpose, report components, usage timing, alternative tool, and output format. The only minor gap is lack of description for the actual parameters, but the schema already handles those adequately with 100% coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both repo_path and instance_id have descriptions in the schema). The description adds value by explaining the tool's output and usage context, but it does not elaborate on the parameters themselves beyond what the schema already says. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes a 'knowledge-coverage health score' (0-100) for the codebase, listing specific report components. The verb 'reports' and resource 'knowledge-coverage health score' are specific and distinct from sibling tools like brain_metrics or brain_from_git.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises running 'after brain_from_git or periodically to track knowledge-capture progress,' providing clear usage context. It also mentions using 'skill_gaps to find what to fix,' offering a named alternative for further action. There are no explicit when-not-to-use warnings, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the tool shows authorship (from learn_from_attempts) and related lessons, and provides an example output format. This makes the behavior transparent, though it does not explicitly state that the operation is read-only or non-destructive. The example strongly implies read-only behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence covering purpose, a sentence for usage guidance, and an example. Every sentence earns its place. There is no redundancy or fluff. The structure front-loads the purpose and follows with actionable context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with 2 fully documented parameters and no output schema, the description adequately covers the return value (experts and lessons per file, including example). It does not specify edge cases (e.g., missing files, multiple files), but the example and language imply per-file results. Slightly more detail on grouping or error handling would improve completeness, but it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 meaning via the example usage and explanation of output, but it does not add new semantic details about the 'file_paths' or 'instance_id' parameters beyond what the schema already provides. The example clarifies the format but does not add conceptual depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('show') and resource ('what cachly knows about a list of files — experts + related lessons per file'), clearly distinguishing itself from sibling tools like brain_who_knows (which focuses on who knows a file) and brain_conflicts (conflicts). It immediately conveys the tool's unique value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit, actionable guidance: 'Call this before starting work on unfamiliar files, or in sync_file_changes to see what knowledge exists.' This gives clear context for when to use it. It does not explicitly state when not to use or alternatives, but the guidance is specific enough to be highly useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 will 'learn which jobs have been fixed, broken, or are stable' which implies internal state change. However, it does not disclose whether the operation is idempotent, destructive (overwrites existing data), or what happens on duplicate entries. This is acceptable for an ingest tool but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding value: purpose, input format, and intended use case. No wasted words, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no enums, no output schema, and a clear ingest purpose, the description is mostly complete. It explains what the tool does, what it expects, and when to use it. It could briefly mention if the operation is synchronous or batched, but for the complexity level, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 and their subfields. The description adds meaning beyond the schema by explaining the purpose of 'prev_status' ('needed to detect transitions') and the overall learning effect. This is adequate, though the description does not enumerate every subfield.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bulk-ingest CI run outcomes into the Brain'. It specifies the action (ingest), resource (Brain), and the specific domain (CI history). The description also distinguishes the tool from its sibling 'brain_from_git' by explicitly mentioning equivalence, which helps differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage guidance: 'Feed it an array of {job, status, prev_status} objects from your CI system' and 'Use it to bootstrap the Brain from historical CI logs.' While it does not explicitly list when not to use it or compare alternatives among siblings, the context is clear enough for a bulk-ingest operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature implicitly ('Read back'), explains the two invocation modes, and reveals that a default note is returned for missing keys. It does not explicitly state that it has no side effects, requires no special permissions, or any performance characteristics, but it is adequate for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero wasted words. The first sentence states the core purpose, the second explains the two modes of usage, and the third adds the default note behavior and the complement tool. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 2 parameters and no output schema. The description covers purpose, invocation modes, and the missing-key behavior. It mentions the complement tool. The only minor gap is that it does not describe the return format (e.g., JSON object with key-value pairs), which would be helpful for an agent. Overall, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions already present. The description adds value by explaining the behavior of omitting the key (list all preferences) and the return behavior for missing keys ('Returns a default note'). This goes beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read back' and the resource 'preferences stored for this Brain instance'. It distinguishes two modes (single key vs. all) and explicitly names the sibling tool 'brain_set_pref' as complement, making differentiation from the 100+ sibling tools easy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use a key (get a single value) and when to omit it (list all preferences). It also mentions the complement 'brain_set_pref', implying the write counterpart. However, it does not explicitly state when NOT to use this tool or provide exclusions for other read alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries behavioral disclosure. It explains it uses 'CKG causal edges + lesson history' and returns ranked failure modes with fixes. Lacks details on error conditions or response format, but adequate for a prediction tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 params (100% schema coverage), no output schema. Description adequately explains return value as 'top likely failure modes ranked by probability, with pre-loaded fixes.' Could be more detailed on output format, but sufficient for a prediction tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add additional meaning beyond what schema provides for parameters; it only repeats the 'context' example from schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Pre-deploy failure prediction with probability percentages' and specifies inputs (change context) and outputs (failure modes with probabilities and fixes). It differentiates from sibling 'brain_predict' by focusing on failures and deployment readiness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call before any significant deploy, migration, or infrastructure change.' Provides clear context but does not mention when not to use or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the data source ('lessons tagged with service=...') and outputs, but it does not explicitly declare side effects (e.g., whether it's read-only or mutates state). The example implies a safe query, but for responsible AI use, a clear statement of no side effects or required permissions would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three well-structured sentences. The first sentence delivers the core purpose and output, the second specifies the data source, and the third provides usage guidance and an example. Every sentence earns its place without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return values ('operators, known OOM failures, and the fixes that worked'). However, it lacks detail on the exact format (e.g., whether results are returned as a list, a map, or structured JSON). For a mapping tool, specifying the output structure more precisely would improve completeness, but it is sufficient for an AI agent to understand the tool's general behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value beyond the schema by explaining the relationship between the 'service' parameter and stored lessons ('Matches the `service` tag'). It also provides concrete examples ('prometheus', 'cachly-web') and contextualizes how the output depends on the parameter. This enrichment justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Map everything the Brain knows about a running service or system' with specific outputs (operators, failures, fixes). It uses a specific verb ('map') and resource ('service'), and distinguishes itself from sibling tools like brain_file_map or brain_discover through its focus on incident triage. The example reinforces the purpose by showing the mapping result for 'prometheus'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends use for incident triage: 'when a service is misbehaving (e.g. a restarting pod)'. It implies the primary scenario without explicitly contrasting with alternatives. While it doesn't say 'use X instead when Y', the provided context is clear enough to guide when to invoke this tool. A mention of when not to use it would elevate it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes the data source (learn_from_attempts), the ranking criteria (lesson count and confidence), and provides an example output. It does not mention side effects or auth requirements, but the tool appears to be a read-only query, and the description is sufficiently transparent about its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences and an example. It is front-loaded with the purpose, followed by source, output detail, usage context, and a concrete example. Every sentence adds value with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (all explained), no output schema but an example output, and moderate complexity (expert ranking from knowledge graph), the description covers the input, behavior, and usage context well. It lacks error handling details, but the example and clear purpose make it largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter having a clear description. The description adds an example of usage (brain_who_knows(topic="kubernetes deployment") → ...) and implies the default for limit is 10. This adds some context but does not significantly expand on the schema descriptions, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds experts on a given topic using the knowledge graph from learn_from_attempts, and returns a ranked list ordered by lesson count and confidence. It includes an example output, distinguishing it from other brain_* tools that provide different analyses (e.g., brain_conflicts, brain_coverage).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use this tool to find the right person before starting a task or to understand knowledge distribution. While it does not list when not to use it or alternatives, the sibling tools do not offer a direct replacement for topic-specific expert finding, making the guidance clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the auto-expiration after ttl_ms to prevent deadlocks and explains the Redis SET NX PX mechanism. This provides sufficient behavioral context for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only three sentences, each adding value: action, return value, and usage guidance with sibling tool. It is front-loaded and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and return value (fencing token). However, it omits details on retry behavior (retries, retry_delay_ms) and failure scenarios (e.g., lock not acquired). Still, it is sufficient for a lock acquire tool with good schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all 5 parameters (100% coverage). The tool description adds no additional parameter meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool acquires a distributed lock using Redis SET NX PX (Redlock-lite) and returns a fencing token. It distinguishes from sibling cache_lock_release by advising to use it for early release.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions using cache_lock_release to free the lock early, providing a clear alternative. However, it does not specify when not to use this tool or other potential alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It reveals the Redis RPUSH operation and optional TTL, but does not clarify whether multiple calls append or overwrite, or discuss failure modes. Adequate but leaves some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences covering purpose, storage, and companion tool. No redundant words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple append-to-list operation, the description covers purpose, storage, and optional TTL. It does not specify return value, but that is minor. Contextually adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with property descriptions. The description adds context beyond schema by explaining storage under cachly:stream:{key} and the pairing with cache_stream_get. It does not add new parameter details but enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool caches a list of string chunks via Redis RPUSH, provides the storage pattern, and mentions the sibling cache_stream_get for replay. It distinguishes from other cache tools by specifying the list data structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case (LLM token stream) and implies the tool is for appending to a list. It does not explicitly state when not to use it, but the sibling context helps. Minimal but sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 destructive behavior ('permanently delete', 'deprovisions Kubernetes workload', 'removes all data', 'irreversible'). This adequately informs the agent about the tool's irreversible side effects and scope of impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first states purpose, the second elaborates consequences. No unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, no output schema, no nested objects), the description covers purpose, behavior, and key consequence (irreversibility). It does not specify return behavior (e.g., success message) but that is minor. It is largely complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters (instance_id, confirm). The description adds no extra meaning beyond the schema. The word 'irreversible' implicitly justifies the confirm parameter, but no direct semantic enrichment is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Permanently delete a cache instance'. It specifies the resource (cache instance) and verbs (delete, deprovision, remove). It distinguishes from siblings like 'cache_delete' (which deletes a cache key) and 'create_instance' by emphasizing irreversibility and full deprovisioning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when permanent deletion of a cache instance is needed) but does not explicitly state when not to use or mention alternatives. For example, it doesn't contrast with 'cache_delete' or warn about data loss impact. While context signals provide sibling names, the description lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses the return type (list with key, category, size, TTL, preview) and scope (project-level cached entries). It implies read-only behavior without side effects, which is appropriate for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words. The first sentence establishes purpose; the second adds valuable detail about output and usage context. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema or annotations, the description covers the returned fields, purpose, and decision context. It omits default limit behavior and pagination, but overall is adequate for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description does not add further parameter details beyond the schema. It mentions return fields, which indirectly helps understand the category filter, but does not explain defaults or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists cached context entries, specifies the returned fields (key, category, size, TTL, preview), and distinguishes it from siblings by focusing on listing all entries for a project rather than retrieving a specific entry or recalling context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: 'so you can decide whether to recall existing context or refresh it.' It implicitly suggests alternatives (recall_context, cache_get) but does not explicitly name them or give when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description clearly explains sorting logic (in-progress first, then planned by priority) and that it returns a single item. Lacks details on edge cases (e.g., empty) but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-loaded with action and purpose, no wasted words. Efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with no output schema, description covers key behavior, sorting, and usage timing. Return structure is implicit; no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds no extra semantics beyond implying tag is optional and filters; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifies verb 'Get', resource 'roadmap item', and unique behavior 'single most important next actionable', differentiating from siblings like roadmap_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Call at session start to immediately know what to work on next', implying ideal timing, but no explicit when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It explains the summary storage, next session display, and Ambient Learning from git log. However, it does not disclose potential side effects (e.g., whether data is overwritten), response behavior, or error conditions. More detail on the learning process 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each serving a distinct purpose: purpose, integration with next session, and additional feature. It is front-loaded with the core action and remains concise without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity and the presence of 5 parameters with 2 required, the description covers the essential behavior and the optional Ambient Learning. It could mention return values or error handling, but for a save operation it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds useful context: it explains that workspace_path enables Ambient Learning and that summary should be '2-3 sentences'. This goes beyond the schema's basic descriptions, providing actionable guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: saving a session summary when finishing work. It specifies what is recorded (accomplishments, files changed, lesson count) and mentions how it integrates with session_start. This distinguishes it from siblings like session_start and session_ping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this when ending a work session, before going idle, or before summarizing,' providing clear usage contexts. It does not mention when not to use or compare to alternatives like session_handoff, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It describes the output as health metrics, but does not disclose whether it is read-only, cached, or any side effects. Adequate but minimal given the simple, non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first lists core capabilities, second provides usage guidance. No wasted words, front-loaded with essential info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description lists the specific metrics returned. Combined with the tool's simple nature, it provides sufficient context for an agent to decide when to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description correctly implies no input needed. Baseline score of 4 applies as no parameter information is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a clear verb 'Show the health of the global Knowledge Commons' and lists specific metrics (total lessons, confirms, top categories, etc.). Differentiates from siblings like syndicate, syndicate_search, and syndicate_trending which focus on other actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use for weekly reviews or to explore what the community knows', providing clear context. Does not specify when not to use or directly name alternatives, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It reveals governance bootstrap logic, post-bootstrap admin-only restriction, and explains the implications of each role (admin can manage roles/delete, reviewer has senior-review badge, etc.). This is thorough for a role assignment tool, though it does not mention whether reassignment overwrites or errors on duplicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, then role definitions, then governance note, then example. It is not overly long and every sentence serves a purpose. Minor redundancy in repeating the role list could be trimmed, but overall it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, roles, auth, and provides an example. However, it lacks any mention of return value or error handling (e.g., what happens on success, what if the handle doesn't exist). Given the tool has 4 parameters and no output schema, the agent would benefit from knowing if it returns confirmation or result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by expanding on the role enum with detailed permissions (e.g., 'reviewer can senior-review (🛡️ badge, stronger recall boost)'), explaining governance bootstrap (making 'assigned_by' optional initially), and providing a concrete usage example. This goes beyond the schema's concise descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'assign' and resource 'role to a team member on a shared brain instance'. It lists the four specific roles and distinguishes what each allows. This differentiates it from sibling tools like team_roster or team_audit which manage membership or logs, respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to assign roles) and provides important context: first call bootstraps governance (no auth needed), subsequent calls require admin. An example is given with 'assigned_by'. However, it does not explicitly direct the agent to alternative tools like team_grant_scope for scope management or 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.
Behavior4/5
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 tool is read-only by describing it as returning data and clarifies data source: 'Built automatically from learn_from_attempts(author=...) calls — no setup needed.' This implies no side effects and no destructive behavior, which is sufficient for an overview tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, output details, and usage/background. It is front-loaded with the key verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must describe the output. It lists returned fields (lesson count, top domains, last-active date), which is helpful. It lacks details on ranking criteria and output format, but for a simple overview tool, this is largely sufficient. The description compensates well for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions). The tool description does not add any extra meaning beyond what the schema already provides. For example, it does not explain how `top_n` affects the output or how `instance_id` is used. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Full team expertise overview — who knows what, at a glance. Returns a ranked table of all contributors...' This is specific and distinguishes it from sibling tools like team_roster (listing members) and brain_who_knows (likely more specific lookups). The verb 'returns' and resource 'expertise overview' are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists use cases: 'Use for onboarding (who to ask about X?), retrospectives, or to find knowledge gaps.' This provides clear guidance on when to use the tool. It does not mention alternatives or when not to use it, but the scenarios are specific enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 tool stores a lesson and that it shows up in team_recall with attribution. It does not mention any destructive behavior, auth requirements, or side effects. The description provides some behavioral context but is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, efficient sibling comparison, and outcome. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
10 params, 5 required. With 100% schema coverage, description covers core behavior and differentiates from sibling. No output schema. It does not explain if multiple lessons per topic are allowed or idempotency, but is reasonably complete for a storage tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: explains `author` is required for team attribution, mentions `topic` format ('category:keyword'), and notes the lesson's appearance in team_recall. This adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool stores a lesson in a shared team brain ('Store a lesson in a shared team brain'). It distinguishes from sibling `learn_from_attempts` by noting it requires an author name. This is a specific verb-resource combination with sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly says it is like `learn_from_attempts` but REQUIRES an author name, giving a clear context for when to use this over the sibling. It also mentions the outcome (`Shows up in team_recall with 'by <author>'`). However, it does not explicitly state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: proposes a merged version, shows contributions by author, consensus, union of failures, and canonical lesson. The word 'proposes' implies non-destructive action, which is helpful. Could explicitly state if it modifies or only presents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five concise sentences, front-loaded with the core purpose. Each sentence adds value: action, context, output summary, and usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what the tool does, the scenario (multiple contributors, same topic), and the output elements (contributions, consensus, failures, canonical version). Could be slightly more detailed about the output format or merging algorithm, but is adequate for a proposal tool with two simple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds no extra information about parameters beyond the schema's field descriptions. Baseline of 3 is appropriate as schema already documents the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool merges multiple contributors' lessons into one canonical version, using specific verbs ('merge', 'synthesize') and resource ('team brain lessons'). It distinguishes from siblings like brain_federate and brain_diff by focusing on consensus/union across multiple authors on the same topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides two concrete use cases: 'when onboarding new team members or before documenting a process.' While it doesn't list sibling alternatives, the context sufficiently guides when to apply this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses that the operation is READ-ONLY and specifies the scope (last 1 hour). It explains the behavioral nuance of surfacing conflicts instead of silent overwrites, providing valuable context beyond a simple 'list'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with 'READ-ONLY', and every sentence adds value. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, no output schema, and explanatory context about conflicts and agent writes, the description is complete. An agent can understand what the tool returns and why it exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with instance_id described as 'Brain instance ID'. The description does not add extra semantic detail about the parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists unresolved belief conflicts and writing agents, framing it as an arbitration inbox. It distinguishes itself from the sibling tool brain_resolve_conflict by noting that conflicts can be resolved with that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (when multi-agent teams share a Brain and contradictory writes occur) and directs users to brain_resolve_conflict after listing. It does not explicitly state when not to use it, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that the tool is read-only, has no side effects, no external network calls, no rate limits, and results are inline (nothing cached or persisted). It also explains scope fallback behavior. Missing is the output format or structure, but overall transparency is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. It front-loads the safety disclaimer, then explains purpose, usage context, and scope details in a logical flow. Every sentence adds value, and there is no redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers safety, usage timing, and parameter behavior well, but the absence of an output schema means the agent is left without any description of the return format (e.g., structure of predictions, confidence levels). This gap is significant for a prediction tool, making completeness only adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 valuable functional meaning to the scope parameter (e.g., 'instance = this brain only (today’s behaviour)', 'org = cross-team Org Knowledge Graph'), which goes beyond the enum values in the schema. Top_k and context are not enhanced, but the scope explanation warrants a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a read-only Predictive Pre-fetch Engine that reads the CKG to predict failures and return highest-confidence fixes. It uses specific verbs and resources, and distinguishes itself from siblings by emphasizing its read-only nature and inline results without persistence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Call at session start when working on a specific feature or debugging area.' It also advises when to widen scope to org. However, it does not directly compare to alternatives like brain_predict_failures or brain_plan, leaving room for confusion among similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility. It transparently describes the consequences of each winner choice: for 'success' it 'reaffirms the fix' and the failure stops blocking recall; for 'failure' it retires the fix, decays CKG edges to ~0, and archives the lesson. Also notes human-in-the-loop as the strongest signal. No contradictions, but could mention reversibility or permission needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences: first defines the overall action, second details the outcomes, third gives a crucial usage hint. No unnecessary words. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action and consequences, but does not mention the output/return value. Since there is no output schema, the agent is left wondering whether the tool returns a confirmation, status, or error. Also missing error conditions and prerequisites beyond listing conflicts. Adequate but with a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaning of the 'winner' values in context (what 'success' and 'failure' actually do). Other parameters are well described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool's purpose: 'Arbitrate a contested topic by picking the winning side.' It explains the two winner options in detail and distinguishes itself from the sibling tool brain_conflicts (which lists open conflicts). The verb and resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance: 'List open conflicts first with brain_conflicts.' This implies the prerequisite step and directs the user to the appropriate sibling tool. However, it does not explicitly state when not to use this tool or discuss alternatives in more detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly discloses that the action is irreversible (share URL becomes invalid) and warns that users with imported copies keep them locally. With no annotations, this provides important behavioral context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences—each adds unique value: action description, consequence, and example. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two required parameters and no output schema, the description fully explains the tool's effect, side effects, and includes an example, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have clear descriptions in the schema. The description adds a usage example but does not add semantics beyond what the schema already provides, warranting a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Revoke and permanently delete') and resources ('public Brain share by its share ID'), clearly distinguishing it from siblings like brain_share and brain_share_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating the share URL becomes invalid and no one can import it. However, no explicit alternative is given when the user wants to temporarily disable a share.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states return behavior (content or null) and glob matching. However, it lacks explicit statements about side effects (none), idempotency, or safety, which would further enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first states purpose, second gives usage guidance, third provides glob examples. No redundancy, efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple retrieval tool: covers purpose, when to use, parameters with examples, and return format. No output schema needed; the description explains the return value sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds valuable context: explains glob patterns with examples ('file:*', 'arch*') and the meaning of the key parameter. It also clarifies the return value, going beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and resource 'previously saved context from the cache'. It distinguishes from siblings by mentioning glob pattern support and returning null if not found, differentiating it from tools like cache_get or remember_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use this at the START of any task to check if you already have relevant context cached, before doing expensive operations'. It implies when to use but does not explicitly mention alternatives or when not to use, though the cost-saving hint is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the minimum author convergence (2+), the condition for crystallization (cross-person signal), and the non-destructive nature (surface in view). However, it does not explicitly state whether the operation is read-only or write-heavy, nor potential side effects beyond creation. Still, the depth of behavioral explanation exceeds typical tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that is front-loaded with purpose. It efficiently uses examples and contrasts. Slightly busy but every sentence adds meaning; could be split into list or distinct sections for even better scannability, but remains concise given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a concrete example of the output format. It covers preconditions, uniqueness criteria, and output surface. The high complexity and 3-param schema are well-addressed. Lacking an explicit list of return fields or edge cases, but the example compensates. A slightly richer return description would push to 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter has a description in the input schema. The tool description echoes the schema's info on 'label' auto-generation and 'min_authors' defaults but does not add new semantic value beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and the resource ('Team Crystal'), explicitly differentiating from the sibling 'memory_crystalize' by describing the cross-author convergence requirement. The purpose is unambiguous and distinct among 80+ sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (for cross-person pattern detection) and when not to (vs memory_crystalize for individual compression). It specifies prerequisites: 'Needs attributed lessons (learn_from_attempts(author=...) / team_learn)' and mentions where results surface ('crystal_view'), providing clear context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full weight. It discloses that the tool 'classifies and stores lessons automatically' and returns a summary. While it does not cover auth or rate limits, it gives sufficient behavioral insight for a storage operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, with the purpose front-loaded. Every sentence adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description is largely complete. It explains purpose, usage, and return. Minor gaps exist around error handling or edge cases, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context by describing the observations as 'commands run, errors seen, solutions found', but this does not significantly enhance the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('auto-learn'), the resource ('session observations'), and distinguishes it from the sibling tool 'learn_from_attempts' by noting it works 'WITHOUT explicit learn_from_attempts calls'. It also specifies usage at session_end.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Use at session_end') and contrasts with an alternative ('even if you forgot to call learn_from_attempts'), effectively differentiating it from the sibling tool learn_from_attempts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 the behavioral impact: 'The Brain adjusts lesson confidence automatically — confirmed failures get +15%, false positives get −10%.' It also notes it's called automatically. However, it does not describe behavior for 'cancelled' status, error handling, or what happens if required parameters are missing—only the main numeric effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no filler. It front-loads the primary purpose, then immediately lists key effects and usage context. Every sentence provides essential information—nothing extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description explains the core action, confidence adjustments, and both automatic/manual triggers. However, it does not describe the return value or response format, which leaves agents uncertain about what to expect after invocation. It also doesn't cover edge cases like empty topics or cancelled status.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all parameters have descriptions), so baseline is 3. The description adds value by explaining 'scan_topics' is 'Used to detect false positives' and connects 'job_status' to the confidence adjustments. This goes beyond the schema's bare descriptions, enriching semantic understanding for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Close the CI feedback loop: tell the Brain whether a CI job passed or failed and which topics it covered.' It uses a specific verb ('confirm') and resource ('CI'), and distinguishes itself from siblings like 'brain_predict' (which predicts failures) and 'fedbrain_confirm' (federated equivalent) by focusing on closing the loop after CI execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: 'Called automatically by cachly-action at the end of every pipeline. Also use manually after a deploy to confirm or refute the brain's last prediction.' This covers both automatic and manual use cases. However, it does not explicitly state when NOT to use this tool versus alternatives like 'brain_from_ci' or 'brain_predict_failures', which could help the agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 privacy-safe nature, what data is shared, the confidence bucket mapping (high/medium/low from numeric input), and the aggregation condition for meta-lesson derivation. This provides good context beyond the schema. However, absent is any mention of return behavior, idempotency, or side effects like whether repeated calls are safe. Still, for a contribution tool, this is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, each with a clear purpose: first sentence states the core action and what is shared, second explains the aggregation mechanism, third gives usage guidance. There is no redundancy or filler. The most important information (purpose and privacy) is front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description covers the essential aspects: what it does, what is shared, the privacy angle, and when to use it. The aggregation trigger is explained. It does not describe the return value or confirmation, but since no output schema exists, this is not a critical gap. The description is complete enough for an agent to decide when and how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with full descriptions, so baseline is 3. The description adds value by explaining that the confidence parameter is 'bucketed before sending' into high/medium/low categories, and that topic_category should be normalized (e.g., 'auth:jwt'). This context goes beyond the schema's basic type and enum descriptions, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Contribute a privacy-safe signal to the global Brain commons.' It specifies exactly what is shared (topic category, outcome, confidence bucket) and what is not shared (lesson text, org identity). It also distinguishes from the sibling tool fedbrain_contribute by explicitly noting the privacy requirement, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Use this instead of fedbrain_contribute when privacy is required (enterprise, GDPR).' This clearly indicates the context for using this tool versus the alternative. However, it does not explicitly state when not to use it (e.g., when privacy is not a concern, use fedbrain_contribute), which would strengthen the guidance. Still, the alternative is named and the condition is clear, earning a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses the tool's behavior: it returns a structured changelog with categories (new, updated, recalled, decayed) and mentions the output format from the format parameter. It does not mention destructive effects, rate limits, or auth, but the read-only nature is implied and the description is sufficiently transparent for a diff tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a brief example. Every word adds value, with no redundancy. The front-loaded analogy and immediate explanation of the output make it easy to grasp quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the return structure (categories of changes). It also provides an example output. It lacks details on edge cases or pagination, but for a changelog tool of moderate complexity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining the meaning of the parameters in context (e.g., 'since' as time window, 'instance_id' as cache instance) and providing an example that illustrates their usage. The description also clarifies the output structure beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly communicates that the tool provides a changelog of AI Brain changes, using the analogy 'git log for your AI Brain.' It explicitly lists the types of changes (new, updated, recalled, decayed), which distinguishes it from sibling tools like brain_search and brain_predict.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests usage for weekly reviews with the example 'What did my AI learn this week?' and provides a concrete usage example. It does not explicitly state when not to use it or compare to alternatives, but the context is clear enough for an AI agent to determine appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description implies a read-only operation ('Browse') and shows an example output without side effects. It does not explicitly state that this is a non-destructive, safe-to-call operation, but the context is strong enough to infer. The description adds value by explaining the nature of the marketplace (curated, community-verified lessons), but a more explicit statement about no state changes would elevate it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, contextual background, usage guidance, and an example. Every sentence serves a purpose without redundancy. It is front-loaded with the core action and then provides supporting details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must explain the return value. It provides an example output ('☸️ Kubernetes Incident Brain · 42 lessons · install: brain_install(slug="k8s")'), which gives a good idea of the format. However, it does not explicitly state that the function returns a list of such strings (or a single string), which would improve completeness. Given the simplicity of the tool (1 optional parameter), the description is very close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the only parameter (min_confirms: 'Only count lessons with at least this many community confirmations (default: 1)'). The main description does not mention the parameter at all. Since the schema already provides full meaning, the description adds no additional value beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Browse the Domain Brain marketplace' and lists it as a listing of curated, installable packs. The verb 'browse' specifies the action, and the resource 'marketplace' is distinct from sibling tools like brain_install (which installs) and brain_search (which searches specific brains). The example output further clarifies the tool's behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends when to use the tool: 'Use at onboarding or when starting work in an unfamiliar domain.' It also provides an alternative by mentioning brain_install, stating 'Install one with brain_install(slug="...")'. This gives clear guidance on when to use this tool versus a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 tool returns config snippets for 7 clients, a Brain ID, and a model-neutrality proof table. It also states that all clients connect to the same Brain for shared data. This covers core behavioral traits, though it does not mention any side effects, required permissions, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence captures the core value proposition. The rest provides specific, actionable details (list of clients, autopilot option, example output). Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (one parameter, no output schema), the description is largely complete. It explains the return value sufficiently for agent understanding. However, it could be slightly improved by noting the output format (e.g., JSON) or any prerequisites (e.g., a running instance). The presence of 7 sibling tools with similar names is mitigated by the distinctive purpose stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (instance_id is described in the schema). The description adds value by explaining what the tool does with that instance_id (generate configs for the associated Brain). It goes beyond the schema by detailing the output content (config blocks, model-neutrality table). The baseline credit is met, and the description provides meaningful additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: exporting memory configuration for portability across AI editors. It specifies the verb ('Bring your own model, keep your brain') and the resource ('returns Brain ID and config snippets for 7 clients'). It distinguishes this from sibling tools like 'syndicate' and 'brain_share', which focus on sharing or federating data rather than generating client configs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: when you want to connect multiple editors to the same Brain. It mentions an alternative ('autopilot to configure all detected editors in one command'). However, it does not explicitly state when NOT to use this tool (e.g., if you only need a single editor config, or if you lack an instance_id).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the tool is read-only with no side effects, which is essential behavioral information. However, with no annotations provided, the description could also mention potential error handling (e.g., what happens if instance_id is invalid) or rate limits, though the given context is still satisfactory for a monitoring tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each adding value: first sentence states purpose and metrics, second asserts safety, third explains parameter, fourth gives usage guidance and links to siblings. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameter, usage context, and differentiators. It lists the metrics returned, which helps set expectations without an output schema. It does not explain error handling, but for a simple read-only tool, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already describes the instance_id parameter. The description adds guidance to obtain the ID from list_instances, which reinforces but does not significantly expand beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves real-time stats for a cache instance and enumerates specific metrics like memory usage, hit/miss rate, commands/sec, connected clients, keyspace info, and uptime. It also distinguishes itself from sibling tools by explicitly stating it is not for reading cached values (use cache_get) or key-level info (use cache_exists or cache_ttl).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use for monitoring, capacity planning, or debugging performance issues; do not use for reading cached values or key-level information, with specific sibling tool references. This gives clear when-to-use and when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses no side effects, explains return values (-1 for no expiry, -2 for missing key). Since no annotations exist, the description fully covers 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Purpose, return behavior, and usage guidance all in minimal text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return values. Could mention error conditions, but sufficient for a simple TTL check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds little beyond parameter names. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves the TTL of a key in seconds, and distinguishes itself from siblings like cache_get (value) and cache_set (set expiry). Specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes read-only nature and directs to cache_set for setting TTL. Provides context for when to use, though lacks explicit when-not-to-use statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: free tier provisions in ~30 seconds, paid tiers return a Stripe checkout URL. It also lists all available tiers with sizes and pricing. No annotations are provided, so the description carries the behavioral burden and handles it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences front-load the purpose and tier details, with no redundant or wasted language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description covers the creation process, tiers, and basic behavior. It could mention return values for free tier, but overall it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for both parameters. The description adds value by explaining 'name' is unique and listing tier options with details not in the schema (e.g., 'Dragonfly + Semantic Cache' for speed tier).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'managed Valkey/Redis cache instance on cachly.dev'. It distinguishes from sibling tools like delete_instance, get_instance, and list_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to create a cache instance) and mentions free vs paid tiers. While no explicit alternatives are given, the tool's purpose is distinct among siblings. The guidance on starting with 'free' tier is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly indicates a read-only operation ('inspect', 'shows') and mentions no destructive actions. The tool's behavior is transparent for a simple inspection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first defines the verb and resource, second adds details and usage guidance. It is front-loaded, efficient, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers purpose, outputs, and usage timing. It could explicitly state the read-only nature, but the context is adequate for an inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic parameter descriptions. The tool description adds value by explaining the crystal's purpose and what outputs to expect, enriching the parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects the Memory Crystal and lists specific outputs (top patterns, lesson count, refresh time). It differentiates from sibling tools like memory_crystalize by emphasizing inspection rather than modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Call after session_start when you want to quickly see accumulated wisdom.' It does not name alternatives but implies this is for inspection, which is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly discloses side effects: propagates confirmation globally (increments confirm_count on knowledge certificate), updates local CKG confidence, and triggers Gold Standard at threshold. No contradictions with non-existent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero waste. First sentence states core action, second explains effect, third gives success criterion. Front-loaded with key verb and noun.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage and no output schema, description is complete enough. It explains input requirements (syndicated lesson id, outcome, optional topic), process, and outcome. The only minor gap is no mention of error conditions or authorization requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds value by connecting parameters to real-world context: 'id' is from fedbrain_search results, 'topic' updates CKG confidence, 'outcome' has enum with clear meaning. It explains the purpose of each parameter beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: confirming that a syndicated lesson worked, with specific verbs ('confirm', 'propagates', 'increments', 'updates') and a distinct outcome (Gold Standard at 10 confirmations). This distinguishes it from siblings like fedbrain_search (search) and fedbrain_contribute (publish).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies when to use: after consuming a syndicated lesson from fedbrain_search results, to confirm its effectiveness. It does not explicitly state when NOT to use (e.g., for lessons not syndicated) or mention alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: mutation, immediate email, irreversibility via MCP, caller requirements, and error conditions. No annotations provided, so description fully carries the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the key mutation flag. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate complexity (3 params, no output schema), the description covers purpose, behavior, requirements, roles, and error conditions completely for an agent to decide invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaning beyond schema: default role, valid roles enumerated, and error handling for duplicate email. Provides useful context for correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends an invite email and invites a team member to a Cachly organization. It distinguishes itself as a mutation, but does not explicitly differentiate from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites (caller must be admin/owner), valid roles with descriptions, default role, and error conditions (already member or pending invite). However, no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: PII stripping, irreversibility, and return format. However, with no annotations provided, the description could also mention required permissions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused paragraph, front-loaded with the main action. It is concise but could be slightly improved with better sentence separation for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description covers all necessary aspects: purpose, usage guidelines, parameter context, return value, constraints (irreversibility), and alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds context like 'Topic key (used as public category)' and 'Framework/platform tag (nextjs, fastapi, go, docker, etc.)' but does not significantly enhance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Publish a lesson to the Cachly Public Brain' and distinguishes from sibling tools by explicitly naming alternatives for private lessons (learn_from_attempts, global_learn) and anonymized sharing (syndicate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use vs alternatives: 'Use learn_from_attempts or global_learn for private lessons; use syndicate for anonymized global sharing without framework tagging.' Also warns about irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: returns most recent successful lesson with confidence indicator, explains badge meanings for staleness, and reveals a side effect (resetting confidence clock to 1.0). This exceeds expectations for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is appropriately sized: first sentence states purpose, second gives usage guidance, third details return value and badges, fourth notes side effect, and ends with an example. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return content (lesson with confidence, badges) and side effect. Could be slightly more precise about return format, but the example helps. Comparable sibling tools exist, but the description is sufficient for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are well-described. Description adds value with an example and reinforces partial match support but does not introduce new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool recalls best known solutions from past lessons with a specific verb (Recall) and resource (best known solution). It differentiates by explicitly advising to call it before tasks that might have been done before, which distinguishes it from sibling tools like recall_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: 'Call this BEFORE attempting any task that might have been done before.' While not specifying when not to use, the context effectively implies the alternative is to proceed without prior knowledge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: declares read-only and no side effects, describes return format (array with key, value, similarity_score, namespace), explains empty results, and details embedding computation (server-side, pgvector, data stays in Germany). Missing some error handling details, but still thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single coherent paragraph with front-loaded purpose, then read-only, return format, requirements, examples, and sibling references. Every sentence adds value with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no output schema, the description covers return structure, requirements, examples, and behavior. Slightly lacking error/edge case details, but overall complete for a search tool with well-documented schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 context like default values and explanation of hybrid search, but the schema already covers parameters well. No significant additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Find cached entries that are semantically similar to a natural-language query', which clearly identifies the verb and resource. It also distinguishes from siblings by referencing cache_get for exact lookup and smart_recall for brain lessons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use cache_get for exact key lookup; use smart_recall for brain lessons', providing clear alternatives. It also includes prerequisites (API key, tier) and examples, giving complete guidance on when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description transparently describes the tool's behavior: it stores progress, TODO lists, changed files, instructions, and incomplete work, and states that the next session automatically includes this handoff. It does not mention edge cases like overwriting, but provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no unnecessary words, front-loads the main action, and uses bullet points for clarity. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, nested objects), the description covers the main behavioral flow and the importance of calling it before closing. It could be more complete by explaining the instance_id parameter or the format of context_summary, but overall it adequately prepares the agent for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds value by explaining the purpose of each parameter in context (e.g., 'remaining_tasks: Tasks NOT yet done — the next window MUST pick these up' and for files_changed: 'marks partial/broken files so next window knows to fix them'). This goes beyond the schema's brief descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool saves a detailed handoff for the next chat window, listing specific stored items and explicitly distinguishing itself from siblings like session_start and session_end by specifying when to call it (BEFORE closing a chat window).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to call this tool BEFORE closing a chat window, especially if work is incomplete, and explains the consequence (prevents the 'continue' problem). It provides clear usage context but does not explicitly 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It describes the tool as returning a scored subset of lessons, implying a read-only operation. It details the scoring dimensions (relevance, recall count, severity, recency, outcome). However, it does not explicitly state if it is non-destructive or if any side effects occur (e.g., logging). A minor gap, but generally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence states purpose and output, second sentence gives usage guidance. No redundant information, front-loaded with key details. Extremely concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no output schema, the description covers the tool's purpose, when to use it, and what it returns (scored lessons). It mentions scoring factors but does not detail the exact output structure (e.g., fields returned). This is a minor gap, but overall the tool is well-described for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add significant new meaning beyond the schema; it uses 'focus' and 'top_n' in context but does not elaborate on constraints or formats. The description adds no extra value over the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool returns 'top-N most relevant lessons' for a focus topic, scored by multiple factors. It also distinguishes itself from the sibling 'session_start' by noting it is ideal when session_start returns too many lessons, 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Ideal when session_start returns too many lessons to fit in context (1000+ lesson brains). Use session_start for the full briefing including handoffs, streak, roadmap, and team telepathy.' This tells the agent exactly when to use this tool and when to use the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden—it clearly states this is a non-destructive read/analysis tool that returns prioritized data without side effects, using severity emojis to clarify output structure. No contradictions with missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main purpose, uses emojis and a clear sequence (show → run → return → pairs) without wasted words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two simple parameters, no output schema, and the complexity of a domain gap tool, the description covers purpose, output format, usage pattern, and relationship to sibling. Could add a note about what instance_id must contain (but schema already has it).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by naming the output structure (prioritized list) and explaining how min_failures influences results, enriching the schema's minimal descriptions. The description does not repeat schema details but contextualizes parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool identifies 'knowledge blind spots' using specific categories (unresolved failures, missing attribution, etc.) and distinguishes it from the sibling tool 'brain_coverage' by noting they pair for a full picture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests running periodically and points to brain_coverage for full health picture, but does not explicitly say when not to use it or list alternatives beyond brain_coverage. It implies usage through verbs like 'find where to focus' and 'pairs with'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is read-only ('immutable trail'), admin-only, and that events are automatically recorded. It does not mention potential error conditions (e.g., non-admin access) or rate limits, but covers the essential behavioral traits for a safe audit tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences + example) and front-loaded with the purpose statement. Every sentence adds value, there is no redundancy, and the structure is clear and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, no output schema, and 100% schema coverage, the description is nearly complete. It explains purpose, prerequisites, related tools, and provides an example. The output format is only hinted via the example, which could be elaborated, but for a list view it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds value by linking the requester parameter to the admin requirement and providing an example call with output. This contextual information helps the agent understand parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('View') and the resource ('governance audit log for a shared brain'). It explicitly mentions the immutable trail of role changes and confirmations, and distinguishes itself from sibling tools like team_assign_role and team_confirm by focusing on viewing the audit history rather than performing actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is essential for enterprise compliance and security reviews, and it is admin-only once governance is active. It also mentions that events are automatically recorded on team_assign_role and team_confirm, implying when to use the audit log. However, it does not explicitly state when not to use this tool or name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: writes to disk, overwrites existing files, returns file content and path, no auth beyond instance_id. Describes the generated file's lifecycle hooks. Lacks details on error conditions or validation, but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then behavioral details, returns, and style guidance. Some marketing language ('One command. Every AI. Always on.'), but overall every sentence adds meaningful information. Efficient for the amount of content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description adequately covers purpose, behavior, return values, and usage. It explains the generated file's effects. Minor gaps like error handling or invalid instance_id, but for this tool's scope, it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining instance_id (UUID of cache instance), enumerating all editor options with context, clarifying project_name usage, and defining style enum with defaults and purpose. This goes beyond the schema's descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool generates a CLAUDE.md / copilot-instructions.md file for AI self-management. Uses specific verbs ('Generate', 'Writes') and resource. Distinguishes from sibling tool 'setup_ai_memory' by explicitly naming it as an alternative for interactive setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('makes any AI self-managing forever') and an alternative ('Use setup_ai_memory instead if you want an interactive one-shot setup'). Also explains style options (minimal vs full) giving clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the copy operation, privacy constraint, domain filtering, and confidence threshold. Does not detail merge semantics or reversibility, but for a non-destructive knowledge transfer, this is reasonably transparent. No annotations to contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus a short example. First sentence states purpose, second distinguishes from sibling, third gives example. Front-loaded, no fluff, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, and parameter roles well. Lacks description of output/return value (no output schema) and error conditions. Does not mention side effects or post-invocation behavior. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 5 parameters with descriptions (100% coverage). Description adds context by explaining domain values, default confidence (0.6), dry run preview, and includes an example call. Goes beyond schema by providing usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'copy ... from source brain into your brain', identifies tool as private org knowledge transfer, and contrasts with syndicate_search (global, anonymous). Example shows concrete use case (new hire) and domain values. Clear differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for private org knowledge transfer within the same Cachly org or with shared source. Directly contrasts with syndicate_search as alternative for global, anonymous search. Provides prerequisite conditions and an example scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes use of text heuristics, low overhead, and specific return values. No side effects or destructive actions implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Purpose, performance, and output examples front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter; description covers all necessary aspects: function, method, performance, and output format. No output schema or further details needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% with clear description. Description adds value by listing possible output namespaces, going beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States verb 'classify', resource 'prompt', and outcome '5 semantic namespaces'. Clearly distinguishes from siblings; no similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states usefulness for understanding namespace caching. Lacks explicit when-not-to-use or direct alternative comparison, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: deduplication (updates existing topic with audit trail), contradiction detection (warns on conflicting outcomes), confidence decay (1.0 → 0.7 after 5d → 0.5 after 10d), and structured metadata handling. This is comprehensive and leaves no major behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long (multiple paragraphs) but well-structured: it starts with purpose and when-to-call, then lists key fields, behavior details, and an example. Every sentence adds value, though the example and some behavioral notes could be slightly trimmed. It is front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters (4 required), no output schema, and no annotations, the description covers purpose, usage, parameter highlights, deduplication, contradiction detection, and confidence decay. However, it does not describe what the tool returns (e.g., confirmation, error messages) or any error states, which is a minor gap. Overall, it is nearly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 summarizing key fields (topic, outcome, what_worked, what_failed, context) and providing an example that demonstrates usage patterns. It also connects parameters to behavioral features like deduplication (topic) and confidence (outcome), enhancing semantic understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores a lesson learned from attempts, with a specific verb ('Store') and resource ('lesson'). It distinguishes from sibling tools by explicitly mentioning recall_best_solution for future recall, and provides concrete usage scenarios ('deploy, debug, fix, architecture decision').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to call ('AFTER completing any non-trivial task') and explains that lessons will be recalled automatically via recall_best_solution. However, it does not explicitly state when not to use this tool versus alternatives like team_learn or global_learn, which are present in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It details exactly what the tool does (scan, detect contradictions, merge duplicates, flag stale entries, compute health score), its side effects (merge, flag), and the return report content. There is no contradiction with missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences and a brief analogy. It front-loads the core purpose and uses no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately describes the return value (full report with conflicts resolved, duplicates merged, before/after count). It covers when to run, what it does, and the parameters' effects, making it complete 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The tool description adds minimal extra context, such as referencing 'stale entries' and '90 days' which aligns with the stale_days parameter, but does not significantly enhance understanding beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a cognitive memory consolidation garbage collector that scans lessons, detects contradictions, merges duplicates, flags stale entries, and computes a health score. It distinguishes itself from siblings like memory_crystalize and brain_doctor by specifying its role as a weekly consolidation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises running weekly or when brain_doctor reports >20 lessons, and provides an analogy to git gc. While it gives clear context for use, it does not explicitly state when not to use this tool or list alternatives, but the guidance is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: overwrites existing values, returns a confirmation object with key, stored_at, ttl. Missing details on error handling or access controls, but sufficient for a cache write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise single paragraph with purpose, use cases, behavior, and example. Slightly verbose but all information earns its place. Front-loaded with primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the return format is described. Covers main function, overwrite, and companion tools. Lacks discussion of error cases but adequate for a simple cache write tool given context complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining the category and ttl defaults, and provides an example usage pattern that clarifies parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves context to cache for later recall, with specific examples like codebase overviews and file summaries. It distinguishes from siblings by mentioning retrieval via recall_context and listing via list_remembered.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (caching context, avoiding re-computation) and names companion tools (recall_context, list_remembered) for retrieval and listing. The overwrite behavior is stated, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 describes the push-based nature, the trigger events, and the return structure (risk_level plus up to 5 ranked warnings with confidence and known fix). However, it does not disclose potential side effects (e.g., does calling this trigger any background processing or state changes?), nor does it mention rate limits or authentication requirements. Still, for a proactive warning tool, the core behaviors 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly packed with useful information in two sentences. The first sentence establishes the tool's unique value proposition (push-based, proactive warning), and the second provides specific usage guidance and return format. No wasted words—every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, no output schema), the description clearly explains trigger events, context mapping, threshold control, and the return structure. It covers what an agent needs to invoke it correctly. Losing a point due to lack of explicit side-effect disclosure and the absence of any output schema to supplement return value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 goes beyond by explaining how each event_type maps to context content (file path vs. title+body vs. description) and how threshold controls noise. This adds meaningful usage context that helps the agent set parameters correctly. One point off because the instance_id parameter is not further elaborated beyond its schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'proactively checks whether the file you just opened, the PR you are about to raise, or the deploy you are about to run matches any known failure pattern — and surfaces warnings BEFORE something breaks.' It uses a specific verb ('surfaces warnings'), specifies the resource ('known failure patterns'), and clearly differentiates from siblings by emphasizing its push-based, proactive nature, distinguishing it from other brain_* tools that are likely pull-based.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call this tool: 'Call this on file_open (with the file path as context), pr_open (with the PR title/body), or deploy (with a short description of what is being deployed).' It also provides clear context for interpretation based on event_type. While it does not explicitly state when not to use it, the given triggers are specific enough that alternative tools (e.g., brain_predict_failures) are implied for other scenarios. This is excellent guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly states 'Read-only — no side effects', reveals fallback behavior for org_id parameter, and describes return behavior including null for missing/expired keys. No contradictions. Could add information about error handling (invalid instance_id), but the current disclosure is thorough for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose and return behavior, then read-only note, then sibling alternatives. No filler or redundant information. Every sentence adds distinct value. Perfectly structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with 3 parameters and no output schema, the description covers purpose, return types, key behavior, side effects, and alternatives. Missing explicit mention of error behavior (e.g., invalid instance_id) but the return of null for missing/expired handles the most common cases. Slightly short of fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 repeats the org_id fallback logic already present in the schema description. It does not add new insights beyond what the schema already provides for key or instance_id. No compensation needed, but also no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get a value from a running cache instance by key') and resource ('cache instance'). It specifies return types (string, deserialized JSON object, null for missing/expired) and distinguishes from siblings by not mentioning multiple keys until the guidelines section. This is a specific, unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names three sibling tools (cache_mget, cache_exists, semantic_search) with exact conditions for their use. Provides clear when-to-use and when-not-to-use guidance without ambiguity. No other tool in the sibling list is directly relevant to single-key retrieval, so these exclusions are sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 clearly states that the operation overwrites existing values, is not idempotent for new data, returns 'OK' on success, and errors on invalid/paused instances. It does not, however, mention any concurrency behavior or performance implications, which are minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loads the core purpose, and each sentence earns its place: first sentence defines the operation and non-idempotence, second explains return values and error cases, third clarifies value type and TTL. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description compensates by specifying the return value ('OK' on success). The parameter set is well-documented via the schema. The only minor gap is no mention of max key/value sizes or character limits, but for a cache set operation this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and explains all 5 parameters. The description adds value by explaining that 'value' can be a string or JSON-serialized object (not explicit in schema), and reinforces the TTL semantics (omit for no expiry). The schema does not mention JSON-serializable, so the description adds meaningful context beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Set', 'Overwrites') and clearly names the resource ('key-value pair in a running cache instance'). It distinguishes itself from siblings by explicitly naming cache_mset and cache_stream_set as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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: it mentions cache_mset for setting multiple keys in one round-trip and cache_stream_set for caching LLM token streams. This directly helps the agent choose among sibling caching tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 tool returns diagnostic data and appears read-only, but does not explicitly state non-destructiveness or any required permissions. However, the description implies safe usage ('call this FIRST') and lists fix steps, suggesting no side effects. A higher score would require an explicit statement about mutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for the tool's complexity. It front-loads the key instruction and then lists returns and workflow. Slightly verbose in listing all return items but remains clear and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains what the tool returns (API reachability, JWT, user ID, brain instances with status indicators, Redis ping, fix steps). It also provides the workflow. For a zero-parameter diagnostic tool, this is complete and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema coverage is 100%. The description adds value by explaining the return content in detail, but since parameters are absent, the baseline is 4. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a full diagnostic for the 'cachly Brain' and should be called first for troubleshooting. It lists specific return items (API reachability, JWT validity, user ID, brain instances, Redis ping, fix steps), making the purpose unambiguous and distinguishing it from sibling tools that handle cache, learning, or instance management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'call this FIRST whenever anything is not working' and provides a clear workflow: run, read issue, fix, retry. This gives strong guidance on when to use the tool and how to incorporate it into a troubleshooting process.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It explains that the tool computes scores based on age, recall frequency, and outcome, and returns a ranked list with visual confidence bars. It implies a read-only operation without destructive side effects, but does not explicitly state idempotency or safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a visual example. It front-loads the main purpose and uses a metaphor ('old knowledge rots') to make it memorable. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (3 parameters, 1 required) and no output schema, the description fully covers what the tool does, how it works, what the output looks like, and when to use it. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, but the description adds semantic value by explaining that 'show_top' returns entries sorted by lowest confidence first, and that 'min_age_days' defaults to 0 (all). This goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool computes a decay score (0–100%) for lessons based on age, recall frequency, and outcome. It specifies the resource (lessons in a Brain) and the action (confidence scoring), distinguishing it from other brain-related tools like brain_predict or brain_doctor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific use case: 'Use this before a big refactor to know which lessons to trust and which to re-validate.' While it doesn't explicitly exclude other contexts or compare to alternatives, the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description provides good behavioral context: it returns filtered history, shows lesson evolution (failure → partial → success), and explains the 'before' date logic. It does not disclose authentication needs or rate limits, but it covers the core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a tagline, an example question, and a brief explanation of output and utility. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and no annotations, the description is complete enough. It explains what the tool returns (filtered history with evolution stages), when to use it, and parameter formats. An agent can reliably select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning beyond schema by explaining topic slug format ('deploy:api'), date format (ISO string), and the 'BEFORE this date' semantics. It also gives an example query, enriching understanding of each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: returning the history of a topic before a specified date, showing evolution. It uses a memorable metaphor 'Brain Archaeology' and provides an example question. It distinguishes from siblings like 'global_recall' and 'recall_best_solution' by focusing on temporal point-in-time queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage scenarios (e.g., understanding old code decisions) but does not explicitly state when not to use it or mention alternatives. It implies context for historical analysis, which is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden of behavioral disclosure. It clearly indicates this is a read-only query ('Show your own role and capabilities… Tells you what you can do') and conveys a non-destructive, safe operation. It lacks explicit mention of authentication requirements or rate limits, but the scope is narrow and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tightly written sentences with zero waste. The first sentence states the core action, the second adds depth on output, and the third gives a concrete use-case instruction. It is front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description clarifies what the tool reports (role, capabilities, contact for upgrades). Among 80+ siblings, many are mutation-heavy (team_assign_role, get_instance) or exploratory (brain_graph). This description is self-contained for a simple identity query. Minor gap: no mention of error cases (e.g., instance not found) but adequate for standard use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both handle and instance_id have descriptions. The description goes beyond the schema by framing the tool's purpose and the instance as a 'shared brain instance'. It does not add specific parameter formatting or validation rules, but it orients the agent on how to interpret the parameters in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Show') and specifies the resource ('your own role and capabilities on a shared brain instance'). It adds concrete detail about what is shown ('what you can do (store, review, manage roles)') and context about post-onboarding usage. Among sibling tools like team_assign_role or brain_who_knows, this description uniquely positions team_whoami as a self-identity check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent or user to run this 'after onboarding to confirm your role was set correctly', providing a clear when-to-use directive. It also mentions 'who to contact if you need a higher role', which complements role-checking. This effectively distinguishes it from tools like team_assign_role (which modifies roles) or team_roster (which lists others).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Transparently explains pipeline usage, overwrite behavior, partial failure commitment, and error list. No annotations provided, but description fully discloses behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two sentences followed by behavior summary. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description clearly states return format and partial failure handling. Complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds minor nuance (per-key TTL vs native MSET) but does not significantly enhance schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it sets multiple key-value pairs in a single pipeline round-trip with per-key TTL. It explicitly distinguishes from native MSET.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use cache_set for single key, cache_stream_set for large payloads, and implies cache_mset for multiple keys with TTL.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden. It declares read-only ('does not modify any stored data'), describes the return format ('ordered chain of concepts with confidence scores plus the matching solution' and 'empty chain with a message if no causal path is found'), and includes an explicit example. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: start with purpose, then prerequisites, return behavior, example, and sibling differentiation. Every sentence adds value; no redundancy. The format is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers all essential aspects: what it does, prerequisites, return on success and failure, an example, and guidance on when to use alternatives. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 repeats the schema's explanation for instance_id and problem, adds default for max_depth, and explains tags as 'Optional: narrow search to these tags'. No additional semantics beyond schema are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Root Cause Analysis through memory', tracing a causal chain from root cause to symptom and surfacing a past solution. It distinguishes itself from siblings like recall_best_solution and syndicate_search by emphasizing the full-chain output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states prerequisites ('brain must have lessons stored via learn_from_attempts or brain_from_git') and provides precise differentiation from siblings: 'Use recall_best_solution for direct topic lookup, syndicate_search for community patterns, and causal_trace when you have a symptom and need the full root-cause chain.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly declares the tool as READ-ONLY, with no side effects: outputs text only, writes no files, makes no network calls. It also explains the downstream effect of the generated scripts (HTTPS calls). This fully discloses behavior without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with key information front-loaded (READ-ONLY, outputs text only). Each sentence adds necessary detail without fluff. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple script generation tool with no output schema, the description adequately covers what the tool does, how to use it, and the consequences. It addresses prerequisites (instance_id), output format, and post-installation behavior. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so baseline is 3. The description adds value by explaining the purpose of the output (shell scripts) and the manual installation step, which complements the schema. It does not repeat schema descriptions but provides contextual usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates shell scripts for git post-commit hooks and/or GitHub Actions steps. It specifies the output type and purpose, distinguishing it from other tools in the sibling list that perform learning, caching, or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit instructions: 'You must manually copy and install the output' and 'Run once per repository.' It also notes that no auth is required, guiding when to use the tool. However, it does not explicitly contrast with alternative tools or state 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-destructive nature, return values, and valid frameworks. Without annotations, this provides substantial behavioral context, though missing auth or rate limit info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first covers behavior and returns, second covers usage guidance. No wasted words, well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, behavior, return values, usage context, and sibling references. No output schema, but return described sufficiently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds value beyond schema by listing valid frameworks (enum-like) and noting default for limit. Schema coverage is 100% so baseline 3, but useful extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Import community lessons from the Cachly Public Brain for a framework' with additional details like non-destructive behavior and return values. Distinguishes from siblings such as publish_lesson and learn_from_attempts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using this tool to bootstrap a new brain before first session_start, and points to alternatives (publish_lesson, learn_from_attempts) for other tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses performance characteristics (extremely fast, one Redis SET, no blocking) and the provider-switching behavior, compensating for the lack 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with purpose, every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fully explains the tool's behavior, timing, and parameter roles, making it complete for its intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-defined. The description adds minor context (e.g., provider list) but does not significantly enhance meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a lightweight checkpoint for saving current task and files touched, distinguishing it from session_start and session_end by explaining the provider-switching use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to call every ~5 tool calls or after a significant step, and contrasts with session_end by explaining the checkpoint persists even without explicit end.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: 'Read-only — no side effects', 'Returns the count... integer 0 to N', 'Duplicate keys... counted separately (Redis behavior)'. Covers all relevant behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but slightly verbose. Every sentence adds value, but could be tightened. It is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return value (integer count) and edge cases (none exist, all exist, duplicates). With 2 required params and no enums/complexity, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context: instance_id is from list_instances, keys are exact only (no glob). This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks existence of keys in a cache instance, specifically mentions Redis EXISTS, and distinguishes from siblings cache_get and cache_ttl by stating when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Use this to check presence before a cache_get to avoid null handling, or to verify a cache warm-up completed.' Also contrasts with cache_get (if you need value) and cache_ttl (if you need expiry info).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses idempotency, prefix storage (cachly:global:lesson:), global recall via global_recall, no rate limits, and return type (confirmation with key). This fully covers 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficient but somewhat long (5 sentences). Front-loaded with purpose and key behaviors. Every sentence adds value, though could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and many siblings, description covers all essential context: idempotency, storage location, recall method, usage guidelines, example, and parameter format hints. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds context beyond schema: provides example topic format ('category:keyword'), explains instance_id purpose (though not necessary), and gives a usage example. Adds meaningful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores cross-project lessons, with specific verb 'Store' and explicit resource 'lesson that applies across ALL your projects'. It distinguishes from siblings by naming learn_from_attempts and team_learn with their specific use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool and when to use alternatives: 'Use learn_from_attempts for project-specific session lessons; use team_learn to share lessons with your team.' It also notes idempotency and global recall.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries behavioral transparency. It discloses identity anonymization (HMAC hash), idempotent update behavior, immediate searchability, automatic file path stripping, and the return structure. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured. Each sentence adds meaningful information: purpose, privacy, return, usage context, idempotency, scope, and a security warning. While not overly wordy, it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no output schema), the description covers all essential aspects: return shape, idempotency, privacy, timing relative to learn_from_attempts, and scope. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by noting automatic file path stripping for what_worked and emphasizing the topic format. This slight but useful addition elevates the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Contribute a verified lesson to the GLOBAL Cachly Knowledge Commons...' It uses specific verbs and resources, and distinguishes from sibling tools like syndicate_search and learn_from_attempts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance: 'Call this AFTER every learn_from_attempts that is worth sharing universally.' Also warns against using for secrets/PII and explains scope options. Clearly differentiates when to use this vs. alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It details the lifecycle transitions, clarifies that archived lessons are excluded from smart_recall but preserved for audit, and explains the dry_run parameter behavior. This is comprehensive for a maintenance tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences plus a key-value summary of the lifecycle. It is front-loaded with the primary action, then usage guidance, then behavioral details, and finally parameter specifics. Every sentence adds unique value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (one required), zero output schema, and moderate complexity, the description completely covers behavior, lifecycle, defaults, and safe usage. It is self-sufficient for an agent to invoke correctly without needing external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 the dry_run parameter's default behavior and context (reports changes without writing), and the archive_days and provisional_threshold parameters are semantically tied to the lifecycle ('provisional', 'low-recall lesson'). However, it does not elaborate on instance_id beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 specific verbs and resources: 'sweep and maintain your Brain', listing concrete actions (flags provisional, archives, resolves contradictions). It effectively distinguishes itself from siblings by describing a maintenance operation unique to brain_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage context: 'Safe to run on a schedule (weekly CI job) or on-demand before a big release.' It also describes the lesson state lifecycle (active → provisional → archived), guiding when the tool is appropriate and what effects it has, though it doesn't explicitly mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly declares the tool as READ-ONLY with no side effects, no writes, and no external network calls. Since no annotations are provided, the description carries the full burden and excels by being upfront about the safety profile. It also clarifies what the return value contains (failure modes, concrete steps, checklist) and requires a valid instance_id, giving full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the critical READ-ONLY label. It packs significant information into a concise paragraph with clear sections: safety declaration, purpose, examples, output structure, and usage guidance. Every sentence adds value, and there is no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, 100% schema coverage, no output schema, no annotations), the description provides complete context: it explains the tool's role, input requirements, output structure, and usage timing. The presence of sibling tools like brain_predict increases the need for differentiation, which the description handles well. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 role of each parameter: it mentions 'requires a valid instance_id' and gives example values for the task parameter ('upgrade Postgres 14→16', 'add Stripe webhooks'). However, it does not explicitly describe the top_k parameter's behavior beyond what the schema provides, which prevents a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear READ-ONLY label and then provides a detailed verb+resource definition: 'Generative planning layer on top of the CKG' that returns an ordered action plan. It explicitly contrasts with brain_predict by stating 'brain_plan answers what should I do, in what order?', which effectively distinguishes it from sibling tools. The purpose is 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Call before starting non-trivial work.' It also provides a clear when-not-to-use alternative by contrasting with brain_predict, and lists example tasks ('upgrade Postgres 14→16', 'add Stripe webhooks'). This gives the agent strong guidance on invocation context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States read-only and explains error conditions (instance not found or belongs to another account), which is essential behavioral context beyond the parameter schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, front-loaded with purpose, and every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a tool with one parameter and no output schema: lists returned fields, error cases, and relationships to siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of the single parameter with its description. The description adds value by referencing error context related to the parameter, but the baseline is 3, so +1 for added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full metadata for a specific cache instance, listing the fields. It distinguishes from sibling tools like get_connection_string and list_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: call list_instances first to get valid UUIDs, and use get_connection_string if only the redis:// URL is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, no side effects, return format (list of objects with topic, lesson text, severity, tags), and behavior for optional topic parameter (partial match, limit of 50). Since no annotations are provided, the description fully covers 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Six sentences, front-loaded with key info, no wasted words. Every sentence adds value—purpose, safety, return format, filtering behavior, and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no nested objects, no output schema), the description is fully adequate. It covers all behavioral aspects, return fields, and usage constraints. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains that `topic` performs partial matching and that omitting it returns all lessons (up to 50). The schema already describes both parameters well, so high schema coverage reduces need, but the description still provides valuable context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read-only retrieval of cross-project lessons stored via global_learn' with specific verb and resource. Distinguishes from siblings `recall_best_solution` and `team_recall`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('lessons that apply universally across all projects') and when not to use, with named alternatives for project-specific and org-scoped lessons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, return format (array of objects with specific fields), empty array if no instances, no pagination, and typical account size (<20), covering key behavioral traits beyond annotations (which are absent).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with main action, then read-only, return format, usage guidance—all in a few sentences with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description fully covers the tool's behavior, return format, typical usage, and relationship to sibling tools, making it complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description cannot add parameter semantics beyond the empty schema. Baseline 4 is appropriate for zero-parameter tools; description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all cache instances with status and connection details, explicitly mentions read-only, and distinguishes itself from get_instance and other cache tools that require instance UUIDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use this first to discover instance UUIDs required by all other cache tools' and notes that get_instance retrieves full metadata for a single instance, giving clear when-to-use and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Declares destructive and irreversible nature, safe handling of non-existent keys, and return value (count of deleted keys). No annotations provided, but description fully covers 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with delete action, then explains implications and usage. Every sentence is informative without excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema needed since return value is described. Description covers all necessary context for using this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds context beyond schema: instance_id should come from list_instances, keys must be exact (no glob) and recommends cache_keys to list. Schema coverage is 100% so baseline is 3, but description adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it permanently deletes keys from a running cache instance, distinguishing it from siblings like cache_set, cache_keys, and delete_instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (remove stale entries), when not to use (prefer cache_set with short TTL, don't clear entire instance), and names alternatives (cache_set, delete_instance, dashboard).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![cachly-mcp MCP server](https://glama.ai/mcp/servers/cachly-dev/cachly-mcp/badges/card.svg)](https://glama.ai/mcp/servers/cachly-dev/cachly-mcp)

Score Badge

Copy to your README.md:

[![cachly-mcp MCP server](https://glama.ai/mcp/servers/cachly-dev/cachly-mcp/badges/score.svg)](https://glama.ai/mcp/servers/cachly-dev/cachly-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cachly-dev/cachly-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server