Metis Public Health
Server Quality Checklist
Latest release: v0.1.1
- Disambiguation2/5
With 187 tools covering many overlapping areas (e.g., multiple search tools for different scopes, multiple memory storage tools), it is difficult for an agent to distinguish between them despite detailed descriptions. The high number of similar-purpose tools leads to confusion and misselection.
Naming Consistency4/5Most tools follow a consistent verb_noun pattern (e.g., add_, get_, search_, store_, create_, update_), making navigation predictable. A few exceptions like _obsidian_vault, kg_community, and discovery_intro are minor deviations.
Tool Count1/5187 tools is an extremely large surface for any single server, far exceeding the recommended 3-15. This overwhelms agents and reduces the ability to select the right tool efficiently. The server would benefit from consolidation.
Completeness4/5The tool set is remarkably comprehensive for a public health research assistant, covering projects, tasks, literature, datasets, code, memory, knowledge bases, course building, and many utilities. Minor gaps exist in social/collaboration features, but core functionality is well-covered.
Average 4.2/5 across 187 of 187 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 188 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under AGPL 3.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
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It explains the two argument outcomes but omits side effects (e.g., overwriting existing config), error conditions, and idempotency. For a config-modifying tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and uses a clear Args structure. It is efficient, though the first sentence could be more impactful. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not describe return values or behavior. It also omits prerequisites (e.g., project existence) and error handling, leaving ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It clearly explains project_id as 'The Metis project ID' and write_config with conditional behavior, adding meaningful semantics beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Register a Metis project in Claude Desktop's project list,' using a specific verb and resource. It distinguishes from siblings like connect_project_folder by focusing on registering in Claude Desktop rather than connecting a folder. However, it could be more explicit about the integration target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., connect_project_folder, create_project). The description lacks context on prerequisites or scenarios where this registration is appropriate.
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 mentions recording lineage for reproducibility but does not disclose potential side effects, authentication needs, or what happens if a step is re-recorded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description includes multiple sentences and a parameter list. It is adequately organized with the purpose first, but the parameter list makes it slightly long. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (2 required), no annotations, and an output schema, the description provides a reasonable overview of the tool's role in lineage tracking. It does not cover edge cases or error conditions, but is sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides brief explanations for each parameter (e.g., 'dataset_name: The dataset being transformed'), adding some meaning beyond the schema. However, explanations are minimal and could be more detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a cleaning/transformation step for dataset lineage. It uses specific verbs ('record', 'build') and explains the traceable chain purpose. However, it does not explicitly distinguish from sibling tools like 'clean_dataset' or 'profile_dataset'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Call once per step' and lists step types (recode, filter, join, etc.), implying when to use. But it does not provide explicit guidance on when not to use 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?
No annotations are provided, so the description must carry the burden. It discloses which fields are searched and mentions the archive filter, but does not explicitly state that the tool is read-only or discuss side effects, rate limits, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise with a title line, a brief functional description, and a structured Args section. It front-loads the key extension (include_archived) but the Args section largely repeats schema information, slightly reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of sibling tools and an output schema, the description covers the basic functionality and searched fields. However, it does not explain how results are ordered, what fields are returned, or how pagination works. The 'extended' nature relative to 'search_literature' is not clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds some meaning: 'query' is a search term, 'include_archived' includes archived items, and 'limit' is max results. However, it does not go beyond the schema's defaults or provide constraints like format or allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches literature with optional inclusion of archived items and specifies the fields searched (basename, relevance_note, disease, geography, method). The name 'extended' implies distinction from 'search_literature', but the description does not explicitly differentiate it from siblings like 'search_literature' or 'search_fulltext'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'search_literature' or 'search_fulltext'. The description only states the default exclusion of archived items but does not provide context for tool selection.
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 exist, so the description carries full burden. It only reveals that recurring tasks auto-create next occurrences, but omits other behavioral traits like side effects, authentication requirements, or what happens on validation failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses a clear Args structure but is somewhat verbose. The main purpose is not front-loaded; it starts directly with parameter descriptions. Every line adds value, but conciseness could be improved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (2 required) and no annotations, the description covers parameter meanings and recurrence behavior but does not mention output schema or return format. 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter's role (e.g., 'owner: Who is responsible (default "Metis")', 'recurrence: Optional repeat...'). It adds meaning beyond parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new task in the SQLite database', with a specific verb and resource. It clearly differentiates from sibling tools like add_glossary_term or update_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like update_task or add_journal_entry. The description lacks context about prerequisites, when creation is appropriate, or when other tools should be preferred.
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, description carries full burden. It states it reads reflexion_log entries, aggregates themes, and returns ordering by busiest agent. It does not disclose modification status (implied read-only), performance implications, or error handling. Sufficient for overview 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a code block for the parameter list. Purpose is front-loaded. Minimal waste, though '(Phase 9b)' may be noise. Overall concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters and existence of output schema, description is fairly complete. It explains what is returned (themes, ordering). Lacks detail on what 'top recurring' means or number of themes. Adequate for a focused tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description must add value. It explains agent_slug limits scope (leave blank for all agents) and days defaults to 14. This adds meaning beyond schema defaults, but does not specify format or constraints on agent_slug. Adequate for two simple parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool themes recent reflexions per agent, reading from reflexion_log and returning specific themes. It is specific about verb (theme), resource (reflexions), and scope (per agent). However, it does not explicitly distinguish from sibling 'consolidate_reflexions_tool', so not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explains when to pass agent_slug to limit scope (leave blank for all agents), which implies usage context. However, it does not provide explicit when-not-to-use or compare with alternatives like consolidate_reflexions_tool. Guidance is implied but incomplete.
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?
Discloses the 8000 char limit per source and that output includes source labels. However, it does not mention truncation behavior, ordering, or freshness of content. No annotations exist to supplement, so the description provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly concise, with three short paragraphs. The Args section repeats some information but overall structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite moderate complexity and having an output schema, the description covers core functionality, constraints, and parameters. It is sufficient for basic usage, though edge cases are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds significant meaning: it lists valid source values and explains the date_filters with an example. Both parameters are well-addressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it assembles context from multiple sources for brainstorming, listing specific source types. This is a clear verb+resource pairing, but it does not explicitly distinguish from sibling tools like 'get_context' or 'surface_relevant_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There are multiple context-retrieval tools among siblings, but the description provides no context for selection.
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 behavior. It states the tool searches specific tables and returns top 5 items, but does not mention idempotency, permissions, rate limits, or side effects. It implicitly shows it's a read operation but doesn't confirm.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loading the purpose. It uses bullet-style for the return format and clearly lists the argument. No fluff, though adding structured sections could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown), the description adequately covers return values. It specifies the tables searched and number of results. However, with no annotations, missing behavioral details slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter 'content' with 0% schema coverage. The description adds minimal meaning ('Text to find cross-domain connections for'), but does not elaborate on format, length, or constraints. With low schema coverage, the description should compensate more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds cross-domain connections for given text, specifies the exact tables searched (library_seeded, meetings, news_briefs, ideas), and describes the return format (top 5 with source type, title, snippet). This distinguishes it from siblings like 'find_connections'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the tables searched but does not provide explicit guidance on when to use this tool versus alternatives (e.g., search_library, search_memory). No when-not-to-use or scenarios 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?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the internal process (splitting into items, calling 'capture_idea') and implies that it is a write operation (creating ideas). However, it does not discuss potential side effects like duplicate detection, error handling for malformed files, or rate limits when calling the nested tool. This is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient with 5 concise sentences. The first sentence immediately states the primary purpose. The subsequent sentences provide necessary detail without redundancy. It could potentially be tightened, but overall it is well-structured and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema (not shown but indicated), the description adequately covers what the tool does, how it works, and the parameter. It mentions the internal call to 'capture_idea', which gives context. Minor gaps like idempotency or error states are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage on 'file_path', but the description compensates by explaining that it should be an absolute or METIS_RC_ROOT-relative path. It also lists supported file formats (.txt, .md, .docx). This adds meaningful context beyond the raw schema, helping the agent format the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Import an ideas document... and capture each idea.' It specifies the resource (ideas document) and action (import and capture). It also details the process (reads file, splits into items, calls capture_idea). However, it does not explicitly differentiate this tool from siblings like 'capture_idea' or other scan tools, which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It mentions that it calls 'capture_idea' internally, but does not explain, for example, when a user should choose this over direct use of 'capture_idea' or other import tools. No mention of prerequisites or exclusions.
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 any behavioral traits such as side effects, permissions, rate limits, or whether it is read-only. The agent receives no guidance on safety or consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and includes helpful query examples. However, it redundantly lists parameters in an Args section when the schema already defines them. The front-loading is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return value details are not required. However, the description lacks information about search behavior (e.g., result count, ordering, scope of repository), which would be helpful for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description attempts to add meaning. For query, it adds 'What you're looking for.' For project_id and language, it adds restriction context. However, these are minimal and barely enhance the schema's own parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches a code repository for prior code, variables, and treatments, with concrete query examples. It distinguishes this tool from sibling search tools (e.g., search_library, search_fulltext) by specifying its domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples of queries and mentions what can be found, but does not explicitly state when to use this tool versus alternatives or when not to use it. Usage context is implied, not explicit.
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 explains the meaning of each parameter, which adds transparency. However, without annotations, it fails to disclose whether this is a safe or destructive action, any side effects, or authorization 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and structured, with a clear purpose statement followed by parameter explanations. Each sentence serves a purpose, and it is front-loaded. It is appropriately sized for a simple configuration tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple preference-setting tool with three parameters, the description adequately covers the tool's purpose and parameter semantics. The presence of an output schema reduces the need to describe return values. It does not mention edge cases but is sufficiently complete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions, so the description compensates by explaining each parameter's function. It clarifies that enabled turns tips on/off, power_user sets mode, and snooze_days snoozes for N days. This adds significant meaning beyond the raw schema, though it could be more precise about ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adjusts feature-tips preference, using a specific verb and resource. It distinguishes from sibling tools like next_discovery_tip (show tip) and discovery_status (get status). However, it could be more explicit about the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no usage guidance. It does not explain when to use this tool versus alternatives like next_discovery_tip or discovery_status, nor does it mention prerequisites or exclusions.
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 full burden. It only says 'Retrieve all contacts' but does not disclose behavior like being read-only, pagination, permissions, or any 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and to the point. It could be slightly more structured, but it is efficient with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema is provided, the description is nearly complete. It could mention that it returns all contacts without filtering, but the context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so baseline is 4. The description does not add anything beyond the empty schema, but it is accurate and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves all contacts from the contacts table, using a specific verb ('Retrieve') and resource ('contacts'). It distinguishes from sibling tools like 'update_contact' which is a mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It is the only tool for listing contacts, but no explicit context or exclusions 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 the description carries the full burden. It only states 'Retrieve a stored daily insight' without disclosing behavior on missing dates, idempotence, authentication needs, or side effects. This is insufficient for a tool that mutates no state but has potential error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal yet effective: two lines, front-loaded with purpose, and no unnecessary 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one optional parameter and an output schema (not shown), the description is adequate but lacks information on what happens if no insight exists for the given date. Given low complexity, it barely meets the minimum viable standard.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value by explaining the date parameter format ('YYYY-MM-DD') and default behavior ('Empty = today'). This compensates for the lack of schema-level descriptions (schema coverage 0%). The single parameter is well-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('stored daily insight'). It is specific and distinguishable from the sibling tool 'generate_daily_insight' which creates insights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'generate_daily_insight'. There is no mention of prerequisites, contexts where the tool is appropriate, or when to avoid 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, so the description must fully disclose behavior. It states the tool retrieves publications but does not clarify whether the operation is read-only or if it has side effects (e.g., marking publications as read). The unread_only parameter suggests filtering, but the tool's impact on state is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with a clear purpose statement followed by a short, well-structured args list. Every sentence adds value, and there is no redundancy or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the tool does not need to explain return values. The description adequately covers the parameters and basic purpose. However, it omits details like sort order (likely by date) and potential limitations (e.g., pagination beyond limit). For a simple retrieval, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains each parameter: topic filters by tag (empty means all), limit caps results with default 20, unread_only returns only unread with default True. This adds value beyond the schema, though it lacks details on valid topic values or ordering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves new publications, optionally filtered by topic. However, it does not explicitly differentiate from sibling tools like search_literature or search_library that also retrieve publications. The term 'new' is ambiguous but partially clarified by the unread_only parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving new publications with optional filters, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., search_literature). It also does not mention any prerequisites or context for usage.
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 implies read-only via 'Retrieve' but does not explicitly state it is non-destructive or free of side effects, which is critical for a retrieval 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with a front-loaded purpose and efficient listing of arguments. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers parameters. It lacks mention of prerequisites (e.g., an active research project) or error handling, but an output schema exists so return values are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates: it lists valid section values (overview, articles, milestones, methods) and explains max_chars behavior (default 8000, pass 0 for no limit), adding meaning beyond the schema's type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves research project context and lists components (overview, articles, milestones, methods). However, it does not explicitly differentiate from sibling tools like load_project_context or get_context, 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The phrase 'to help with research planning and writing' is vague and does not provide conditions for use or exclusion.
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?
Without annotations, the description must disclose behavioral traits. It mentions 'active topics' but does not explain what 'active' means, whether pagination exists, or if any filtering is applied beyond the default.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the essential purpose without 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and a likely rich output schema (not shown), the description is minimally complete. However, it lacks context about what constitutes 'active' and does not mention any constraints like maximum results, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%. With no parameters, the description does not need to add param semantics; a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns all active topics from user_topics, specifying the verb 'return' and the resource 'active topics from user_topics'. This distinguishes it from sibling tools like add_user_topic or get_topic_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Given many sibling tools, such as get_topic_memory, the description should indicate use cases or exclusions.
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?
Without annotations, the description carries full behavioral disclosure burden but only says 'Add a topic to track for new publications.' It does not mention side effects (e.g., overwrite existing topic), required permissions, rate limits, or any behavioral constraints. The uniqueness hint in the param description is about parameter validation, not tool 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two lines of purpose and two parameter lines. It is front-loaded with the primary action, and every sentence adds value. There is no redundant or tangential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 existence of an output schema (not shown), the description covers the core add operation. However, it omits context like whether topics persist across sessions, any maximum limits, or connection to the publication tracking system. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description fully compensates by explaining each parameter: 'topic' is uniquely named, 'description' is optional for search criteria. This adds meaningful semantics beyond the schema's bare type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a topic to track new publications. It uses a specific verb ('Add') and resource ('topic'), with a clear purpose. The context for new publications distinguishes it from other 'add_' sibling tools like add_glossary_term or add_journal_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It lacks any mention of prerequisites, when not to use it, or comparison to sibling tools that might also manage tracked items.
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?
Describes writing a file and capturing specific data, which is transparent for a read-mostly operation. However, with no annotations, it should disclose potential side effects (e.g., overwriting files), preconditions (e.g., existence of a journal entry), or failure modes. The description leaves some 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three short sentences covering purpose, captured data, and usage scenario. Each sentence adds value with no wasted words. The structure 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one optional param, has output schema), the description covers most relevant aspects: the brief's contents, file location, and usage timing. However, it omits parameter semantics and any preconditions, making it not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, session_id, is optional with a default empty string, but the description provides no explanation of its purpose or expected value. With 0% schema description coverage, the description fails to add meaning beyond the schema, which is a significant gap for effective tool invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a portable session handoff brief, listing specific captured data and output location. However, it does not explicitly differentiate from similar sibling tools like save_session_summary or consolidate_session_memory, missing a chance to clarify 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using this tool when a session is ending, before /clear, or when switching AI/device. This is good contextual guidance, though it omits when not to use it or mention of 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?
Without annotations, the description carries the burden of behavioral disclosure. It explains the save location and default parameter values, but does not mention any side effects, authentication requirements, rate limits, or whether the operation is reversible. For a content creation tool, more transparency about potential limitations or safety 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise with a single introductory sentence followed by a bullet-like list of arguments. It is front-loaded with the main purpose. Minor issue: the list could be formatted more clearly, but overall it is efficient and each line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (1 required) and an output schema exists, the description covers the input parameters thoroughly and specifies the output file path. It does not describe return values, but that's acceptable since an output schema is present. The description is complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It lists all 6 parameters with clear explanations, default values, and examples (e.g., model options with specific identifiers). This adds significant meaning beyond the basic schema, enabling correct tool usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Generate an image using AI and save it to the PKM', specifying verb and resource. It also details the save path. However, it does not explicitly distinguish this tool from sibling image-related tools like list_generated_images, though the purpose is sufficiently clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks context about appropriate use cases, prerequisites, or which backend/model to choose for different scenarios. It simply describes what the tool does without usage recommendations.
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. It states the basic function but omits details like ordering (ascending/descending?), what constitutes 'recent', scope (all memory types?), or side effects. Minimal disclosure for a tool that likely reads data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a parameter description. 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema, so return values need not be detailed. However, the description doesn't specify the format of memory entries (text, metadata, etc.) or any constraints, which could leave an agent uncertain. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must add meaning. It explains parameter 'n' as 'Number of entries to return (default 10)', which goes beyond the schema's type and default. Clear and helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States it returns the n most recent memory entries with a default of 10, which is clear and specific. However, doesn't explicitly distinguish from siblings like search_memory or get_working_memory, but the name and description imply a distinct list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete use case: 'Useful at the start of a session to recall what was last worked on.' This gives clear context, but does not mention when not to use or alternatives.
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 present, so the description must carry the full behavioral burden. It only says 'append a row' without details on idempotency, side effects, error handling, permissions, or output behavior, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-sentence intro, a one-sentence usage note, and a bullet list of parameters. Every sentence adds value without extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and parameter semantics adequately for a simple audit tool. However, it omits details about the return value (output schema exists but is not discussed) and error behavior, which are needed for full completeness given no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds essential meaning: it explains each parameter's role (e.g., action as 'short description', data_classification with allowed enum values), which the schema lacks. It uses practical examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'append[s] a row to the consent_ledger table' with a specific purpose: audit trail for agent data processing. However, it does not explicitly differentiate from similar logging siblings like log_agent_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'call this whenever an agent processes data', providing clear context for use. No exclusions or alternatives are mentioned, but the guidance is 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?
With no annotations, the description explains the purpose and parameter roles but does not disclose side effects, reversibility, authorization needs, or other behavioral traits beyond persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with purpose, and every sentence adds value. The parameter list is organized and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the six parameters and no annotations, the description covers inputs thoroughly and explains usage. It omits the return value, but an output schema exists, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the tool description provides detailed explanations for all six parameters, including examples and auto-extraction notes for concepts, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records observations during an agent run and mentions it helps recall in future sessions. However, it does not explicitly distinguish from similar sibling tools like add_journal_entry or capture_idea.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to use the tool 'throughout a run' to capture learning, providing clear context. But it lacks explicit exclusions or alternatives, leaving usage boundaries implied.
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 convey behavioral traits. It mentions returning status, classification, warnings, but does not state if it modifies state, stores data, or requires permissions. As a scanning tool, it's likely read-only, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with a clear purpose sentence and structured docstring. No wasted words; front-loaded with the high-level function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and low complexity (2 params), the description sufficiently conveys what the tool does and returns. No further information needed for a scanning tool of this nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description adds meaning beyond schema by defining 'content: Text content to scan' and 'file_path: Optional file path for context-based classification'. This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it scans content for PII patterns and classifies sensitivity level, distinguishing it from siblings like anonymize_text (which transforms) and scanning tools (which search for terms). 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 Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use this tool versus alternatives. It only describes what it does without context for selection.
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 reading reflexions, appending to skill.md, and queuing as draft, and explicitly states the draft is not applied. However, it does not mention side effects (e.g., whether it overwrites existing drafts), permissions, or error handling. The transparency is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is multi-sentence but well-structured: it starts with the main purpose, then details the actions, and ends with a clarification about not being applied. It is concise without extraneous words, though one or two sentences could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters and no annotations, and there is an output schema (not shown) which presumably covers return values. The description covers the main workflow but misses potential prerequisites or error conditions (e.g., what happens if no recent reflexions exist). It is reasonably complete for a straightforward drafting tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions agent_slug in the context of reading reflexions, but the 'days' parameter (default 14) is only vaguely implied by 'recent reflexions' and not explicitly described. The description adds some meaning but leaves the role of 'days' unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool drafts a skill-improvement proposal from recent reflexions, naming the phase (9b), the input (agent_slug), and the actions (appends a section, queues result). It explicitly distinguishes from the sibling 'apply_proposal_tool' by stating the draft is not applied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when drafting a proposal from recent reflexions) and suggests an alternative ('use apply_proposal(id) to write it to disk'). However, it does not explicitly specify scenarios where drafting would be inappropriate, such as if a draft already exists.
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 provided, the description carries full burden. It only mentions 'keyword matching' without details on matching behavior (fuzzy/exact, case sensitivity, fields searched). No information about result ordering, deduplication, or pagination is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences and an Args list. It is front-loaded with the main function and each sentence provides unique value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description covers core purpose and parameters adequately. However, it lacks details on search behavior (e.g., keyword matching specifics, result structure) that would make it fully complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaningful parameter semantics: 'Text snippet to find connections for' for content and 'Maximum results per source (default 5)' for limit, clarifying scope and default behavior beyond name and type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches library, meetings, and news for items related to given text, specifying the tables searched. This distinguishes it from sibling tools like search_library (single source) and semantic_search (different approach).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies usage for cross-source keyword search but provides no guidance on when not to use it or when to prefer other search tools.
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 disclose behavioral traits. It only states the purpose and does not mention that it is read-only, has no side effects, or any required permissions. This is insufficient for an agent to understand the tool's 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise, clearly front-loaded, and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (0 parameters) and the presence of an output schema, the description is adequate but lacks explicit mention of the read-only nature. It covers the basic purpose but could be more complete by referencing the output schema or confirming it is a safe operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema (schema coverage 100%). With 0 parameters, the baseline is 4. The description does not add parameter-specific information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'current backup schedule configuration'. It is specific and distinguishes from sibling tools like 'set_backup_schedule' (which modifies) and 'backup_db' (which triggers backup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading the backup schedule, but does not explicitly state when to use it versus alternatives (e.g., 'set_backup_schedule' for writing). No prerequisites or exclusions are mentioned.
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 provided, the description carries the full burden. It only states the tool lists contexts with active status but does not disclose any behavioral traits like idempotency, cost, rate limits, or safety (e.g., it is read-only).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool is simple with no parameters, the description is largely complete. However, it could enhance completeness by clarifying what 'contexts' are and the meaning of 'active status', or by noting any ordering or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is effectively 100%. There is no need for the description to add parameter meaning; the baseline for zero-parameter tools is 4, and the description meets this without requiring additional explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all user contexts, including general and specialist, with their active status. This distinguishes it from siblings like get_context (retrieves a specific context) and add_specialist_context (creates a context).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of alternatives such as get_context or toggle_context. It lacks explicit when-to-use or 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.
- 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 discloses that the tool appends, refreshes prompt memory, and updates the next_step field. It does not mention destructive effects, auth requirements, or return values, but given the simple mutation, the description is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: three sentences plus a bullet-style args list. The main purpose is front-loaded, each sentence earns its place, and there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 annotations, output schema exists), the description covers purpose, usage timing, parameter meanings, and how it integrates with other tools. It is sufficiently complete 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides clear, human-readable definitions for all three parameters: project_id (slug), what_was_done (1-3 sentence summary), and next_steps (optional, updates next_step). This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a session summary to a project's history and refreshes prompt memory, specifying the verb and resource. It distinguishes itself from general memory tools by focusing on project sessions and mentions integration with load_project_context().
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this at the end of any work session on a project' and explains the history feeds into another function. However, it does not provide guidance on when not to use it or how it compares to alternative tools like add_memory_entry.
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 mentions local model and no API key, but does not disclose side effects like whether existing data is overwritten, performance implications, or error cases. The force_rebuild parameter hints at behavior but lacks detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise with a logical structure: purpose, model info, database convention, then parameter descriptions. It could be slightly shorter by removing the model details if not critical, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not shown), description need not explain returns. However, it lacks details on prerequisites (database must exist), error handling, or success indicators. For a tool with no annotations, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must add value. It explains 'database' is a slug with examples and 'force_rebuild' means re-indexing already indexed files. This provides useful context beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool indexes PDFs into a semantic knowledge base using a specific model. It distinguishes itself from siblings like 'create_knowledge_database' which creates the layer, and 'search_pdf_knowledge' which queries. Examples of database slugs further clarify the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the database must exist (created via create_knowledge_database()), but gives no explicit guidance on when to use this tool vs alternatives like index_library_pdfs. No mention of prerequisites or when to set force_rebuild.
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 behavior. It indicates a write operation ('import') but does not detail side effects (e.g., duplicate handling, overwrite policy), authentication requirements, error conditions, or return value structure. This lack of detail reduces transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences plus an argument description. It front-loads the purpose. However, it could be slightly more structured (e.g., separate sections for usage and args). Still, it avoids verbosity and is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameter tool, the description covers the main purpose and usage scenario. However, with no annotations and an existing output schema (which it does not reference), it lacks information about expected output, error handling, and prerequisites (e.g., file existence, format). It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the parameter, but the description adds meaningful context: 'Full path to the .bib file (e.g. from Mendeley export).' This clarifies that a full path is expected and provides an example usage, which goes beyond the schema's mere name 'Bibtex Path'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's action ('Import papers from a BibTeX file') and the target ('into literature_metadata'). The verb is specific ('Import') and the resource is clearly identified. Among sibling tools, none duplicate this function, so it distinguishes well.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: 'Use this for Mendeley users: export your library from Mendeley as BibTeX, then point this tool at the file.' This guides when to use it. However, it does not mention alternatives or explicitly state when not to use it, so it is not a full 5.
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 full burden. It discloses that the private/ subfolder is never listed, which is a key behavioral trait. However, it does not mention other aspects like sorting, pagination, or whether all files are returned, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main action, and every sentence adds value. It is clear and concise with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately covers the nature of the basket and the privacy exclusion. It could briefly mention the return format but the output schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds context about the basket's purpose and the exclusion of private data, which is valuable beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists files in the Metis basket, specifying the type of documents (legacy & inspiration). It distinguishes from sibling tools like list_folder by naming the specific container and noting the exclusion of the private/ subfolder, which is unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like list_folder or list_backups. It only states what it does and a caveat about privacy but lacks explicit when-to-use or when-not-to-use information.
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 non-destructive ('Never modifies the source file'), performs a PII scan before profiling, and returns a JSON with specific fields. This provides good behavioral context beyond what annotations would offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, format support, behavioral notes, and an Args section. It is concise without wasted words, though some information (like 'never modifies' could be integrated without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 parameters, no annotations, but a clear output schema mentioned), the description covers all necessary aspects: parameter semantics, supported formats, behavioral notes, and output structure. It is complete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the input schema: for 'path' it specifies 'Absolute local path', and for 'sample_rows' it explains the condition (if > 0) and effect on output. With 0% schema description coverage, the description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Profile a tabular dataset' as a specific verb and resource, and lists the outputs (shape, dtypes, null %, unique counts, distributions). It clearly conveys the tool's purpose but does not explicitly differentiate it from sibling tools like clean_dataset or anonymize_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exploratory data analysis but lacks explicit guidance on when to use this tool versus alternatives. It states 'Never modifies the source file' which helps in selecting it for read-only operations, but no exclusions or specific context are provided.
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 of behavioral disclosure. It mentions erasing recorded preference signals and restoring defaults but does not detail reversibility, confirmation steps, or impact on other system components. Basic transparency is present but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences, 20 words) and front-loaded with the core action. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no annotations, and an existing output schema, the description covers the essential behavior. It could mention that the reset is irreversible or that it only affects the thinking profile, but it is largely complete for a simple reset tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description does not need to add parameter meaning, and the baseline for zero parameters is 4. The description is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Clear all thinking_profile_events and reset thinking-profile.yaml to defaults') with a specific verb and resource, and it distinguishes itself from sibling tools like get_thinking_profile and update_thinking_profile by explicitly mentioning resetting to defaults.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as under what conditions a reset is appropriate or what the consequences are (e.g., loss of preference signals). There are no explicit when-to-use or 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It mentions writing to a file and updating a database table, which are key side effects. However, it omits details like overwriting behavior, permissions needed, or whether the action is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is relatively concise with a clear first sentence and a structured Args block. It could be slightly more front-loaded, but overall no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description does not need to detail return values. It adequately covers the key actions (file write, DB update) and parameter purposes. But it lacks mention of error conditions or required preconditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's 'Args' section provides clear semantic meaning for each parameter: session_uuid is the session identifier, title is a short descriptive title, synthesis is key insights in Markdown, action_items are bullet points. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: 'Freeze a brainstorm session as a saved Markdown output.' It specifies the verb (freeze/save) and the resource (brainstorm output), and distinguishes it from siblings like 'get_brainstorm_session' and 'brainstorm_turn' by focusing on output persistence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., session must exist), nor does it compare with similar tools like 'save_session_summary' or 'commit_session_decisions'. Usage context is implied but not stated.
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 and discloses that it searches both a database table (memory_entries) and journal files on disk. It mentions the specific fields searched (title, summary, topics) and the method (grep). This gives good insight into the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 150 words, well-structured with a clear opening sentence, explanatory paragraph, and explicit Args/Returns sections. It is front-loaded and efficient, though could slightly trim the Returns section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 enums, output schema exists), the description covers what it does, how to use it, and what to expect in return. It mentions handling of empty results. It is complete enough 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage. The description adds an 'Args' section explaining both parameters: 'query' as a keyword/phrase to match, and 'entry_type' as an optional filter with listed possible values. This provides meaning beyond the schema's basic titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (search) and resource (memory palace / long-term memory). It explains what kind of context is recalled. However, it does not explicitly distinguish this tool from sibling search tools like search_session_memory or search_library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recalling past context from long-term memory, but it does not specify when to use this tool instead of alternatives like search_session_memory or search_notes. No exclusion criteria are provided.
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 key behaviors: case-insensitive substring search, context lines, truncation via max_chars_per_result, and default limit. However, with no annotations provided, it misses details like response format or what happens with no results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one opening sentence, then a clean bullet list for arguments. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters and an output schema, the description covers parameter semantics and search behavior adequately. It omits pagination or sorting, but for a search tool the core is covered. Output schema likely handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description adds significant value by explaining each parameter: query, scope (with values), limit (default 15), and max_chars_per_result (with truncation behavior).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search', the resource 'markdown notes', and the scope 'across domains, projects, and library'. This distinguishes it from sibling tools like search_library or search_fulltext.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like semantic_search or search_fulltext. The description only lists scope options without clarifying use cases or exclusions.
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 mentions profiling and suggesting operations but does not explicitly state whether the tool is read-only or modifies data. The phrase 'return specific recommended cleaning operations' suggests a read operation, but it should clearly indicate non-destructive 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads purpose, and uses examples and structured Args/Returns sections. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema and lack of annotations, the description adequately explains purpose, examples, and return format. However, it lacks details on supported file formats or behavioral side effects, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by clearly defining 'path' as 'Absolute local path to the dataset file.' This is sufficient for a single string parameter. The description covers the parameter well, though it could accept additional format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool profiles a dataset and returns specific recommended cleaning operations. Examples of suggestions (fill_na, drop_duplicates, strip_whitespace) clarify the resource. It distinguishes from siblings like 'clean_dataset' (which applies cleaning) and 'profile_dataset' (which likely only profiles).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before cleaning operations but does not explicitly state when to use this tool versus alternatives like 'profile_dataset' or 'clean_dataset'. No exclusions or prerequisites are mentioned, leaving the agent to infer context from examples.
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 core action (restore to active) but does not disclose side effects, permissions, reversibility, or output behavior, even though an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short with two sentences plus an Args section. It is front-loaded and efficient, though the Args section could be integrated into the main description for even greater conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter and the existence of an output schema, the description is minimally adequate. However, it misses relational context (e.g., inverse of archive_project) and does not mention error conditions or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the only parameter by stating 'The project_id to restore', which is not present in the schema (0% coverage). It clarifies the parameter's role but lacks details on format or source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Restore' and resource 'archived project', clearly distinguishing it from sibling 'archive_project' which performs the inverse 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but the presence of sibling 'archive_project' implies the usage context. No prerequisites or exclusions are provided.
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?
Mentions auto-extraction of mood and energy, but does not describe behavioral traits like whether it overwrites existing entries, permissions needed, or side effects. With no annotations, more detail would be warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two lines of prose plus parameter descriptions. Every sentence adds information without redundancy. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the essential functionality and parameter meaning. Minor omission: does not explain what happens during auto-extraction or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Provides clear, human-readable explanations for both parameters (content and image_path), which the input schema lacks. This adds significant meaning beyond the schema's property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool stores a journal entry and highlights the key feature of auto-extracting mood and energy. This distinguishes it from sibling tools like add_memory_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as add_memory_entry. The description only states functionality without context for selection.
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 transparency burden. It discloses key behaviors: marks inactive, keeps data, sets status='archived', project disappears from active view but remains available for brainstorm context and search. This is thorough, though it omits details on reversibility (inferred from sibling) and permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: 4 sentences. The first explains the core action and effect, the second technical implementation detail, and the third/arg list. No redundant or unnecessary words. Front-loaded with purpose, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity and presence of an output schema, the description covers the essential behavioral effects and usage context. It lacks mention of prerequisites (e.g., existence of project_id) or explicit note about reversibility (unarchive_project exists), but overall is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions in input schema). The description provides only 'project_id: The project_id to archive.' This adds little beyond the schema's parameter name and type; it does not specify format, source, or constraints. For a single required parameter, this is minimal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Archive a project') and resource ('project'), and explains the effect: marks inactive, keeps data, disappears from active view but remains for context and search. It distinguishes from destructive alternatives like delete/remove, and sibling 'unarchive_project' exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for making a project inactive while preserving data, but does not explicitly state when to use this tool versus siblings like 'remove_project', 'delete_task', or conditions/alternatives. The guideline is implicit in the effect description but lacks explicit 'use when' / 'use instead' clarity.
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, and description does not disclose behavioral traits such as read-only nature, side effects, or limitations. Minimal info beyond the basic 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences and an Args list. All content is relevant and front-loaded with the key action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be described. However, the description lacks constraints (e.g., session existence, empty results) and could be more helpful with brief notes on expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds context to the single parameter: 'The session identifier returned by brainstorm_turn().' This clarifies origin and usage beyond schema title/type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve all turns in a brainstorm session,' specifying the verb and resource. Distinguishes from siblings like 'list_brainstorm_sessions' (lists sessions) and 'brainstorm_turn' (creates turns).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Args section explains that session_uuid comes from 'brainstorm_turn()', providing context on when to use this tool—after a session is created. However, no explicit when-not-to-use 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?
No annotations exist, so the description carries full burden. It discloses progressive disclosure behavior, the combination of vector search and keyword fallback, and filtering by days. It also mentions dependency on fastembed availability. This gives good insight into how the tool operates, though edge cases or failure modes 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured. It starts with a one-line summary, followed by a bulleted explanation of progressive disclosure tiers, then an Args list. Every sentence adds value, and the structure front-loads the key concept. No unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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, output schema present), the description covers all parameters, the progressive disclosure behavior, and the search algorithm. The presence of an output schema means return values need not be detailed here. It lacks handling of empty results or errors, but overall provides sufficient context for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes an 'Args' section explaining each parameter in plain language (e.g., query is natural language, budget_tokens controls progressive disclosure levels, agent_slug for restriction, days for recency). This adds significant meaning beyond the schema's type/default information, effectively compensating for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Recall relevant prior context within a token budget.' It explains the progressive disclosure based on budget and the search approach. While specific, it does not explicitly differentiate from sibling tools like search_memory or surface_relevant_context, which perform similar retrieval tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when prior context is needed within a token budget, and explains the progressive disclosure tiers. However, it does not specify when not to use this tool, nor does it mention alternative tools for different scenarios (e.g., exact search, full-text search). The 'Args' section provides parameter descriptions but no explicit 'when to use' 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 are provided, so the description carries full burden. It does not disclose whether listing is recursive, error behaviors, or permission requirements. This is a significant gap for a file-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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a structured Args section. Every word earns its place. No redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered. However, missing details like recursion depth or performance considerations slightly lower completeness. Still, adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema_description_coverage is 0%, the description adds critical meaning: folder_path is described as 'Absolute path' and pattern as 'Glob pattern to filter files'. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List files in a folder' with a specific verb and resource. The parameters (folder_path, pattern) further clarify the action. This distinguishes it from sibling tools like search_notes or scan_folder_for_intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., search_fulltext). The context of listing files vs. searching is implied but not stated. A score of 3 reflects adequate but missing explicit usage context.
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 the description carries the full burden. It describes the algorithm (embedding, k-means) and return structure but does not explicitly state it is read-only or non-destructive. The word 'propose' implies no side effects, but it's not definitive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear first sentence stating purpose, followed by method details and parameter explanations. No unnecessary content, though a bit more structure could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and an output schema, the description adequately covers inputs and overall behavior. It lacks prerequisites (e.g., need papers in library) but is otherwise comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are explained beyond schema types: n_clusters with auto-detect logic and min_papers with default. This adds significant value since schema description coverage is 0%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool clusters papers by topic and proposes a collection structure, using specific verbs 'cluster' and 'propose' with resource 'papers'. This clearly distinguishes it from sibling tools like search_library or archive_library_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the method (k-means clustering) but does not provide explicit guidance on when to use this tool versus alternatives (e.g., after importing papers). 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but does not disclose behavioral traits such as overwrite behavior, authentication needs, rate limits, or side effects. It also does not describe the output or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two paragraphs: the first states purpose and usage, the second lists parameters. It is front-loaded and every sentence adds value, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides parameter details but lacks information about the output (despite having an output schema), error cases, or prerequisites. For a 10-parameter tool with no annotations, it is somewhat complete but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by providing a clear block with explanations for each parameter (e.g., 'title: Short descriptive name'). This adds significant meaning beyond the schema's types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save' and the resource 'Code Repository', and lists the kinds of code artifacts (script, snippet, function, template). This distinguishes it from sibling tools like search_code_repository.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this whenever the user writes or shares code worth reusing', providing clear when-to-use guidance. It does not mention alternatives or exclusions, but the context is clear.
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 indicates the tool stores data but does not disclose whether it overwrites existing entries, is append-only, requires specific permissions, or has side effects. The 'successful' qualifier hints at a condition but is vague. More behavioral details are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear header, conceptual explanation, and formatted Args list. Every sentence adds value without redundancy. It is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the essential purpose and parameter semantics. It could be slightly improved by noting whether the procedure updates an existing pattern or always creates a new one, but overall it is sufficient for a basic store tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. The Args section adds meaningful explanations for each parameter: 'Short name...', 'Markdown-formatted steps', and 'What situation should trigger...'. This clarifies the purpose and formatting beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores a successful workflow pattern in procedural memory, with a helpful explanation of procedural memory. However, it does not explicitly distinguish this from sibling tools like store_episodic_memory or store_semantic_memory, missing an opportunity to clarify when to use this specific store.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use procedural memory ('repeatable processes, workflows that worked well, step-by-step patterns') providing context. However, it does not specify when NOT to use it or suggest alternatives, which would help the agent decide between this and other memory tools.
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 the full burden. It states it scans and refreshes files but does not disclose side effects (e.g., potential writes, required permissions, or performance impact). Insufficient for a scan-and-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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action verb, no redundant information. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the action but lacks details on prerequisites (e.g., projects must be registered), what 'refreshes CLAUDE.md' entails, and what the output schema returns. Given the presence of an output schema, 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero parameters with full coverage, so there is nothing to explain. The description implicitly conveys that the tool operates on all projects without filtering, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it scans all registered project folders and refreshes CLAUDE.md for each. This distinguishes it from sibling tools like scan_project_folder (single) and full_scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Indicates it's called by dashboard Update button or on demand, providing typical use context. However, it does not explicitly mention when not to use or contrast with 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 carries full burden and discloses key behaviors: auto-tagging, linking to domains/projects, and auto cross-pollination. However, it omits details on idempotency, potential destructive actions, or permission requirements, which are important for a 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficient: a few sentences summarizing behavior followed by a clear args list. Front-loaded main purpose. Could be slightly more streamlined, but overall well-structured and without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters (1 required), no annotations, and a write operation, the description covers primary behaviors but lacks error handling, return value details (though output schema exists), and prerequisites. It is adequate for basic use but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It provides minimal explanations for each parameter (content, source, image_path, auto_cross_pollinate) but lacks depth (e.g., valid values for source, path format). This partially compensates but is insufficient for low-coverage scenario.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores an idea in the SQLite ideas table, using specific verb ('Store') and resource ('idea in SQLite ideas table'). It distinguishes from sibling tools like 'get_ideas' (retrieval) and 'capture_observation' (different domain).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains default behavior (auto-cross-pollinate) and the effect of setting auto_cross_pollinate=False. It gives context on when extra connections are provided, but does not explicitly tell when to use this tool vs alternatives like 'capture_observation' 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 behavioral traits such as side effects, idempotency, or safety. Since this is a read-only report tool, the description should explicitly state it has no side effects, but it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, usage context, parameter documentation, and return value explanation. It is slightly verbose but remains focused and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately explains the return value as a 'formatted status report' covering specific details. No additional information is necessary for an agent to understand what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides a detailed explanation of the 'database' parameter, including its meaning, example value, and default behavior. This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Report' and the resource 'indexing status and coverage for your PDF knowledge bases'. It distinguishes from sibling tools by naming index_pdf_library and search_pdf_knowledge as related but distinct tools, 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'to check how complete your RAG corpus is before relying on grounded answers' and pairs with related tools for indexing and querying. It lacks explicit when-not-to-use guidance, 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.
- 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 states 'Fetch' and returns a JSON array, implying a read-only operation, but does not explicitly confirm non-destructiveness or mention permissions, rate limits, or pagination 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 lines for args, 1 line for return), well-structured with an Args section, and contains no fluff. Every sentence is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (so return values are documented externally), the description's note about 'JSON array of span objects' suffices. However, it could briefly mention span attributes for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 0%, the description compensates by explaining each parameter (session_id, run_id, limit) with defaults and role. This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch recent agent spans' with specific filter options (session, run). This distinguishes it from sibling tools like log_span (creation) and start_span/end_span (lifecycle).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving spans, but does not explicitly state when to use this tool instead of alternatives like search_session_memory or get_agent_runs. No when-not-to-use guidance is given.
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 discloses the database source and filtering behavior but does not explicitly state it is a read-only operation or discuss default parameter behavior (e.g., default status='open' is only in schema, not description).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the purpose, and uses a clean bullet-style list for parameters. Every sentence is informative and no unnecessary text is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the key aspects: source, filters, and limit. It could mention default behavior explicitly but is otherwise complete for a simple query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by explaining each parameter's meaning and allowed values (e.g., status: 'open', 'done', 'blocked', or ''). This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Query tasks from the SQLite database with optional filters,' specifying the verb (query), resource (tasks), and source (SQLite database), which distinguishes it from sibling tools like create_task or delete_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description outlines filter parameters but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage is implied through the parameter list, but no explicit guidance is given.
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 states the output includes title, turn count, and status, and implies recency ordering, but does not specify read-only behavior, sorting criteria, or whether all sessions are included. The presence of an output schema reduces the need for format details, but behavioral traits beyond the schema are under-disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no fluff. The first sentence front-loads the purpose, and the second explains the parameter. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and an existing output schema, the description is nearly complete. It covers the parameter and basic output fields. However, it could enhance completeness by mentioning the ordering (e.g., 'by last modified date') or noting that it excludes archived sessions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'limit' has no schema description (0% coverage), but the description adds meaningful semantics: 'Maximum sessions to return (default 20).' This fully compensates for the schema gap and clarifies the parameter's purpose and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recent brainstorm sessions and enumerates the fields returned (title, turn count, status). The verb 'list' combined with the resource 'recent brainstorm sessions' is specific and distinct from sibling tools like get_brainstorm_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing recent sessions but provides no explicit guidance on when to use this tool versus alternatives (e.g., list_recent_sessions, get_brainstorm_session). With many sibling tools, the lack of exclusions or context leaves ambiguity.
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 records a span and returns a span_id, but does not discuss side effects, idempotency, permissions, or error behavior. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear header, usage example, and parameter list. It is appropriately sized for 8 parameters, though slightly verbose with the example. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (logging a span with 8 parameters, mostly optional), the description covers the core functionality and return value. However, it lacks information about error handling, duplicate detection, or authentication requirements, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema lacks descriptions (0% coverage), the tool description includes a detailed Args section explaining each parameter (name, duration_ms, kind, etc.). This adds significant meaning beyond the schema, compensating well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a completed span in one call, distinguishing it from sibling tools like start_span and end_span. It uses a specific verb (Record) and resource (completed span), and provides an example of retrospective timing data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('for logging retrospective timing data') and contrasts it with needing separate start/end calls, implying when not to use it. However, it does not explicitly name alternative tools or provide 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?
Annotations are absent, so description bears full burden. Mentions the refusal behavior but omits details like whether source is deleted, error handling, or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no extraneous words. Front-loaded with the core action, then constraint, then parameter descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and an output schema (exist), the description covers the main points. Could elaborate on whether the move is a cut or copy, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning by specifying source_path as absolute path in basket/ and target_path as absolute destination (file or folder). This goes beyond the schema's plain string definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (move/promote) and the resource (basket item to project folder). Distinct from siblings like list_basket or archive_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use vs alternatives. Provides a when-not condition (refuses basket/private/ items) but lacks broader usage 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, the description carries the full burden of behavioral disclosure. It describes the tool as performing checks and returning a report, implying it is read-only. However, it does not explicitly confirm non-destructive behavior or mention any side effects, which could be clearer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It uses a brief introductory line, bullet points for checks, and a clear instruction for the result. No extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward review tool with one parameter and an output schema, the description is mostly complete. It explains the checks and the expected action. However, it could mention whether the tool saves anything or provides example output, but the output schema covers the return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the parameter 'slug' with 'The course slug to review,' which adds basic meaning beyond the schema. However, with 0% schema description coverage, more detail (e.g., format or examples) would improve agent understanding, though the parameter is simple enough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run quality checks on a drafted course before publishing.' It lists specific checks and distinguishes itself from the sibling tool publish_course by indicating it should be used beforehand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description positions the tool as 'Step 6' in a workflow and explicitly instructs the agent to fix failures before calling publish_course(). This provides clear usage context, though it does not mention when not to use or list alternative tools.
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 provided, the description carries the full burden but only states that it searches past session summaries. It does not disclose behavior like whether it searches all sessions or only summaries, permission requirements, or result format. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single opening sentence followed by a usage hint and example queries. Every sentence adds value, and the parameter descriptions are compact yet informative. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the description covers the core functionality and parameter semantics. An output schema exists, so return values need not be described. However, additional context about how this differs from sibling 'search_memory' could enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining 'query' as 'Keyword or phrase to search for' and 'limit' as 'Maximum number of results to return (default 10)'. This adds meaningful context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search past session summaries for a topic or keyword' with specific verb and resource. It distinguishes itself from sibling tools like 'search_memory' by specifying 'session summaries' and provides concrete example 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to recall what was discussed in previous sessions' with example queries, giving clear context. However, it does not provide exclusion criteria or explicitly differentiate from similar tools like search_memory.
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 explains the behavioral impact of each policy level but does not disclose potential side effects (e.g., whether changes affect active connections, require permissions, or are reversible). Since no annotations are provided, the description carries the full burden, and more detail on side effects 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three bullet points for policy descriptions and a single line for the argument. No unnecessary words, and the structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter tool with one parameter, the description covers the essential information: parameter definition and policy meanings. An output schema exists (not shown), so return value documentation is not needed. It lacks information on error handling (e.g., invalid policy value) but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant value by enumerating the allowed values ('strict', 'normal', 'offline') and explaining their meanings. It clearly documents the single required parameter. It could be improved by noting case sensitivity or exact format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Set the current network access policy for all agents.' It identifies the action (set), the resource (network access policy), and the scope (all agents). This sufficiently distinguishes it from the sibling tool 'get_network_policy'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the three policy options and their effects, which helps the agent decide which policy to use. However, it does not explicitly state when to use this tool versus alternatives (e.g., checking current policy with get_network_policy) or mention any prerequisites or side effects.
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 responsibility. It discloses that the tool creates records and returns a questionnaire, but doesn't discuss side effects, permissions, or error conditions. However, it is transparent about the core 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear structure: brief summary, then detailed explanation of args and returns. Every sentence adds value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of schema descriptions, the description covers the essential aspects: what it does, the arguments, and the return value. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that explains each parameter's purpose, especially clarifying duration_hours (0 = TBD) and notes. This adds meaning beyond the bare schema, which has no descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('start'), the resource ('course build pipeline'), and provides a detailed breakdown of what it does (create record, add placeholder, return questionnaire). It distinguishes from sibling tools like get_course_status or save_course_curriculum.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It assumes the agent knows to start a new build, but doesn't mention prerequisites, conflicts with existing builds, 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?
No annotations are provided, so the description carries full burden. It discloses that the tool searches memory_entries, ranks by relevance, and returns top N entries formatted as a context brief. However, it does not specify whether it is read-only, requires permissions, or any side effects. The description is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a one-sentence intro followed by bulleted parameter explanations. It is front-loaded with the purpose, and every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and an output schema (not shown but present), the description covers the main behavior and parameter semantics. It lacks detail on the return format, but the output schema likely covers that. The description is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description's parameter documentation adds significant value. It explains 'topic' as topic/task description, 'tags' as optional comma-separated tags, and 'top_n' as max entries with default 5. This is clear and helps the agent understand how to use parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Retrieve'), resource ('past memory entries'), and purpose ('return a structured context brief'). It distinguishes from siblings like 'get_topic_memory' by specifying that it searches by topic and optional tags, ranks by relevance, and formats top N for injection into working context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you need relevant past memory entries for a topic) but does not explicitly state when not to use it or compare with alternatives like 'search_memory' or 'semantic_search'. Usage context is clear but lacks exclusion 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?
The description discloses key behavioral traits: it modifies disk content, creates a timestamped backup for revertibility, and updates the proposal database record. No annotations exist, so the description carries the full burden; it does so adequately with clear 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences plus Args) and front-loaded with the main action. It is well-structured but could be slightly more streamlined by removing the redundant 'writes the proposed change to disk' phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool and the presence of an output schema, the description covers the main behavior and side effects. However, it omits potential failure cases or dependencies (e.g., proposal must exist and be in a valid state), which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter proposal_id is described as 'the id from skill_improvement_proposals', adding crucial context beyond the schema's simple integer type. Despite 0% schema coverage, the description compensates well by explaining the parameter's provenance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Apply a self-improvement proposal' and details the action: writes proposed change to disk, backs up the previous skill.md, and updates the proposal row. This clearly distinguishes it from sibling tools like 'propose_skill_improvement' or 'reject_proposal'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a proposal is ready to be applied, but it does not explicitly state when to use this tool versus alternatives (e.g., approve_proposal, reject_proposal). No when-not-to-use or prerequisite conditions are provided.
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, the description explains the indexing process and persistence, but does not disclose potential side effects like long runtime, disk usage, 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses a clear structure with separate paragraphs for the overview and parameter details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's operation, parameters, and relationship to ask_library(), but does not describe the return value or potential errors. The output schema likely fills this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section that thoroughly explains all three parameters (force_reindex, topic_filter, scope) with concrete examples, fully compensating for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds or rebuilds a PaperQA2 index over PDFs, specifying the resource and action. However, it does not differentiate itself from the sibling tool 'index_pdf_library', which may have similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides when to use the tool (after adding papers, with force_reindex) and explains scope and topic_filter options. It does not mention alternative tools or exclusions, 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.
- 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 the tool fetches external data (CrossRef), compares to local Zotero library, and reports missing references. It implies a read-only operation with no side effects, which is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a one-line summary, a process sentence, and bullet-pointed arguments. Every sentence adds value, though the process sentence could be slightly more structured. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. It covers input parameters and core behavior. However, it does not mention prerequisites like Zotero library connectivity or external API rate limits, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions), but the description adds clear explanations for both parameters: dois as a comma-separated list of DOIs, and label as an optional output file label. This compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Mine reference lists' and specifies the resource 'specific articles'. It explains the process: fetch references for DOIs via CrossRef, check against Zotero library, report missing. This distinguishes it from sibling tools like search_literature which searches broadly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for mining references from specific DOIs but does not explicitly state when to use this tool versus alternatives like search_literature or scan_literature. No exclusions or prerequisites 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?
With no annotations, the description carries full burden. It discloses a write-through guarantee and content truncation to 2000 chars. It also notes that session_id comes from session_bootstrap(). It does not cover error handling or rate limits, but overall adequately discloses key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise, with a front-loaded purpose and a bullet list of event types. The 'Stage 8' label adds minimal overhead. Every sentence serves a purpose, though the list of event types could be integrated more succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple logging tool, the description is complete: it explains what, when, and how to use it, and specifies parameter constraints. The output schema is assumed to cover return values, so no further detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It adds meaning by defining event types ('turn', 'tool_call', etc.), explaining that session_id is from session_bootstrap(), and noting content truncation. This provides valuable context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to persist an atomic event to session_events. It specifies the verb 'persist' and the resource 'session_events', and provides usage context ('call after every tool call'). However, it does not explicitly differentiate from sibling tools, though its logging function is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Call this after every tool call, file write, and classification decision.' It lists event types, providing clear context. It does not mention when not to use or alternatives, but the instruction is straightforward.
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 it pulls prior code, dataset variables/paths, and cleaning steps. However, it does not mention side effects, authentication needs, or whether it modifies anything. For a read-oriented scaffold tool, this is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences plus an Args list, front-loaded with purpose. Efficient and no fluff. Could be slightly more structured, but it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no annotations, but an output schema exists, the description adequately explains the tool's effect and inputs. It covers what is pulled and the steps to follow. Return values are left to output schema, which is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and description provides explicit meanings for all three parameters: goal ('what the new script should do'), project_id ('project to scaffold for, prioritised then cross-project'), language ('r, python, …'). This compensates well for sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it 'assembles raw material to write a new script', specifying verb and resource. Distinguishes from siblings by focusing on scaffolding, not writing or editing. No sibling tool offers similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
States 'Call this, then write the script', indicating it's a preparatory step before script writing. Provides clear context but does not explicitly exclude alternative tools or mention when not to use. However, sibling list has no competing tool, so guidance is adequate.
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 the description carries full burden. It discloses that scanning can be fast (names only) or more accurate (content reading), and that 'none' yields empty results. However, it does not mention error handling, permissions, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a docstring format with a single-line purpose followed by a clear Args section. Each sentence adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (so return values are handled), the description covers the tool's purpose, parameters, and behavioral variations. It lacks potential edge cases like non-existent folders, but overall provides sufficient context for a scanning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides detailed semantics for both parameters: `folder_path` is clearly defined as an absolute path, and `scan_type` enumerates three options with behavior descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Detect a project's purpose from its folder contents,' using a specific verb and resource. It distinguishes itself from siblings like `scan_project_folder` by focusing on intent detection, and details three scanning modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for understanding project purpose via folder scanning, but does not explicitly state when to use this tool versus alternatives (e.g., `scan_project_folder`), nor does it provide when-not or prerequisite conditions.
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, the description carries full transparency burden. It discloses that results are inserted into news_briefs (a side effect) and explains the default query fallback chain. However, it does not cover aspects like rate limits, error handling, or API reliability, which are important for understanding 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It starts with a clear one-line purpose, followed by relevant context about OpenAlex, a side-effect note, and a structured argument list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers the tool's inputs and side effects, and an output schema exists. However, it lacks details on pagination, ordering, or error conditions, which would be helpful for a complete understanding, though not strictly required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, leaving the description to fully define parameters. It explains 'query' with its fallback defaults, 'days_back' as search range, and 'max_results' as result limit. This adds significant value beyond the schema's raw types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Scan OpenAlex for recent papers matching a query.' It identifies the specific resource (OpenAlex) and action (scan), and distinguishes from siblings by naming the source. The additional detail about results being inserted into news_briefs further clarifies the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Free API, no key required' as an advantage but does not explicitly guide when to use this tool over similar siblings like 'scan_literature' or 'scan_news'. The usage context is implied (for OpenAlex papers) but not contrasted with 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 are provided, so the description carries the full burden. It discloses that the tool updates scan_summary, last_scanned, and refreshes CLAUDE.md. It also lists checked items. However, it could be more explicit about any side effects beyond these updates, but overall it is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The main purpose is front-loaded, followed by bullet points of what it checks and updates. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description need not explain return values. It covers the core action, inputs (implicitly), and side effects. Minor gaps: no mention of idempotency or prerequisites (e.g., must have a connected project folder). Still sufficient for a scan tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. The description does not mention the single required parameter 'project_id' or explain its role. While the purpose suggests it refers to the project folder, the lack of explicit parameter documentation leaves ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: scanning a project folder to detect work done since last scan. It lists specific checks (git commits, modified files, todo completions, new documents) and distinguishes itself from sibling tools like 'scan_folder_for_intent' or 'scan_inbox' by focusing on project-specific work detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (scanning a project folder for recent work) but does not explicitly state when to use versus alternatives or when not to use. There are no exclusions or alternative tool mentions, which slightly limits 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 carries full burden. It states the tool 'only persists the configuration' and does not trigger backup, which is helpful. However, it lacks details on side effects, permissions, parameter validation, or confirmation messages, leaving gaps in behavioral clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single introductory sentence establishing purpose, followed by a clear bullet list for parameters. No unnecessary information, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and parameters adequately. Since an output schema exists, return values are not required, but the description omits potential error conditions or prerequisites (e.g., scheduler phase). Nonetheless, for a simple configuration tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so effectively with a bullet list explaining each parameter (enabled, time_utc format, keep_days retention, destination default), adding meaningful context beyond the schema's titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool configures a nightly backup schedule, using specific verb 'configure' and resource 'nightly backup schedule'. It distinguishes from siblings like get_backup_schedule (read) and backup_db (execute backup), leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the schedule is read by the scheduler to trigger backup_db() automatically and that the tool only persists configuration, implying it is for setting up schedules rather than immediate execution. However, it does not explicitly state when to use this tool versus alternatives like get_backup_schedule or backup_db, or specify 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?
Since no annotations are provided, the description carries full burden for behavioral disclosure. It correctly indicates the default incremental behavior and the full sync option. However, it lacks details on potential side effects (e.g., overwriting existing metadata, error states, or rate limits). The description is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it opens with the purpose, then explains default behavior, required environment variables, and the parameter. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one boolean parameter) and the presence of an output schema, the description covers the basic functionality. However, it omits details about return values, error handling, and the extent of the sync (e.g., collections, attachments). It is minimally complete but leaves gaps for a production tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds crucial meaning for the sole parameter 'full'. It explains the default behavior and the effect of setting it to True, which goes beyond the schema's structural definition. This is clear and helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Sync') and resource ('Zotero library into Metis literature_metadata'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools (e.g., import_bibtex_library, scan_literature) by specifying the exact integration with Zotero.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains default behavior (incremental sync) and the option to force full sync via the 'full' parameter. It also lists required environment variables (ZOTERO_API_KEY, ZOTERO_USER_ID), providing context for use. However, it does not specify when to avoid this tool or mention alternatives 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?
Discloses key behaviors: saves transcript alongside audio, updates meetings table, optional diarization with prerequisite (HF_TOKEN). No annotations provided, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (4 sentences plus Args/Returns), front-loaded with main action. Efficiently conveys core functionality and side effects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no annotations, and presence of output schema, the description covers purpose, parameters, returns, side effects, and optional features. Complete for a transcription tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explains that recording_id is the meeting_id from the meetings table, adding context beyond the schema. Single parameter is well-described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it transcribes a meeting recording using Whisper, with specific resource ('meeting recording') and verb ('transcribe'). Distinguishes from sibling 'transcribe_voice' by focusing on meeting recordings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for meeting recordings but does not explicitly compare with alternatives like 'transcribe_voice'. Provides condition for optional diarization but no when-to-use or when-not-to-use 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 provided, so description carries full burden. It describes the return format and steering behavior, but doesn't disclose side effects like session mutation, auth requirements, or rate limits. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose, usage, steering modes, then args. Front-loads the key action and context. Every sentence delivers necessary information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with an output schema, the description covers all essential aspects: what, when, how, steering options, parameter details, and return fields. No gaps for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description's 'Args' section fully explains each parameter's purpose, steering values, session continuation, and optional notes. Completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Run one turn of a brainstorm session' and explains steering modes. It doesn't explicitly differentiate from sibling brainstorming tools like get_brainstorm_session or assemble_brainstorm_context, but the single-turn focus is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this at the start of a brainstorm and after each steering action', and describes each steering mode's purpose. Lacks explicit when-not-to-use or alternative tool names, but provides strong situational 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 responsibility. It discloses the default scan path but omits behavioral details such as recursion depth, idempotency, side effects, error handling, or what happens if the scan_path is invalid. More transparency is needed for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is fairly complete given the tool's simplicity (one optional parameter, output schema exists). It covers purpose, usage guidance, and parameter. However, it does not mention the output format (e.g., list of paths), though the output schema presumably handles that. Slight deduction for not addressing potential recursion or performance considerations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates well by explaining scan_path as 'Absolute path to scan' with a default of 'parent of METIS_RC_ROOT'. This adds meaning beyond the schema, which only has a title and default. Slight deduction for not specifying if relative paths are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it scans a folder for unregistered git repos and article folders, with a specific verb 'Scan' and resource 'folder'. It distinguishes from sibling tools like 'scan_folder_for_intent' by specifying 'unregistered' and 'not yet tracked in Metis', making its purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly indicates usefulness 'for onboarding' and advises to call 'create_project()' for each discovered item. It provides clear context for when to use, though it does not explicitly mention when not to use or list 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 convey all behavioral traits. It explains the paging parameter behavior (default returns all pages, setting True returns only first page). However, it does not explicitly state that the tool is read-only, nor does it discuss side effects, authentication needs, or rate limits. The examples help but leave gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a two-line purpose, a bulleted Args section, and three usage examples. Every sentence adds value, and the structure efficiently conveys all necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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, 1 required, no enums) and the presence of an output schema, the description covers the key aspects: purpose, parameters, and usage examples. It does not detail the return format, but the output schema covers that. It could benefit from mentioning that the tool is a query (read-only), but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides clear explanations for all four parameters: resource (with examples), filters (with format and example), fields (with default and nested field example), and paging (with behavior description). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries DHIS2 metadata, specifies it is a simplified interface and a wrapper around dhis2_query(), and differentiates from that sibling tool by implying it is for common lookups. Examples further clarify the resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description positions the tool as a 'convenience wrapper' for common metadata lookups, implying use when a simpler interface is desired over dhis2_query(). It does not explicitly say when not to use it, but the sibling tool name is mentioned, providing context.
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 burden. It describes the output (plain unified-diff string) but does not disclose side effects, permissions, or error conditions. It's adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load the main purpose, parameter descriptions are compact, and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diff tool with 2 parameters and an output schema, the description covers inputs, output format, and intended use. Could mention edge cases like empty strings or large texts, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description adds meaning for both parameters: 'Original (pre-anonymization) text' and 'Anonymized text from anonymize_text()'. This clarifies the expectation beyond bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a unified diff comparing original and anonymized text, with specific verb 'Return' and resource 'unified diff'. It distinguishes itself from sibling tool anonymize_text by being a complementary diff operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used after anonymize_text by referencing 'from anonymize_text()'. No explicit when-not or alternatives, but the context is clear enough for this simple comparison 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 provided, so description carries full burden. It discloses that the tool takes no arguments, returns a one-line summary with specific fields, and implies it is read-only (reports state). It does not mention side effects, but the non-mutating nature is clear from 'report' and 'read'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded paragraphs. Main purpose in first paragraph, details in second, usage guidance and sibling relations in third, then arguments and return summary. Every sentence is relevant and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and existence of output schema, the description provides enough context: what it does, how to use it with siblings, and what the return contains. It could mention potential error states or performance, but for a simple read tool it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameters with 100% coverage; description adds 'Takes no arguments' which is trivial. No further parameter details needed. Baseline 3 is appropriate as schema already covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reports discovery-tip state and adoption. It uses specific verb 'report' and resource 'discovery-tips state' and 'adoption read'. It distinguishes from siblings by mentioning pairing with discovery_intro and next_discovery_tip and use before set_discovery_tips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use it to answer 'are tips on?' and to sanity-check before set_discovery_tips, and mentions pairing with other discovery tools. However, it does not explicitly state when not to use it or give 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?
The description mentions the passphrase is never stored and uses Python stdlib, which adds transparency. However, it does not clarify whether the original backup file is deleted or if any other side effects occur; the return value mentions 'whether original was removed' but the action is not described. Without annotations, this is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear structure: purpose, implementation note, args, and returns. Every sentence adds value without redundancy. It is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description covers the main aspects: file input, encryption method, and return value. It explains enough for an agent to invoke correctly. However, it lacks detail on error handling and file overwriting behavior, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), but the description adds specific meanings: backup_path is 'Full path to the .sqlite backup file' and passphrase is 'Encryption passphrase.' This goes beyond the schema's titles and provides context that the file should be a .sqlite file, which is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it encrypts a backup file using AES-256-GCM, specifies the output filename pattern, and tells the agent it produces an encrypted version. The verb 'encrypt' and resource 'backup file' are specific, and it distinguishes from siblings like 'decrypt_backup'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a note advising that this is a simple implementation and for production-grade encryption a proper secrets manager should be used. This provides clear guidance on limitations and when to consider alternatives, though it could explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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 duration computation and return format, but does not mention side effects, permissions, or error handling beyond status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses structured Args/Returns format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains parameters return value, covering the essentials for a 3-param tool with output schema. It lacks prerequisite context (e.g., span must be open) but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by explaining each parameter (span_id from start_span, status default 'ok', error optional). This goes beyond the schema's type/default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it closes an open span and computes duration, using specific verb 'Close' and resource 'span'. It distinguishes from sibling 'start_span' and 'log_span'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is used after start_span, but does not explicitly state when to use vs alternatives or provide exclusions. The context of sibling tools makes it clear, but could be more direct.
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 discloses that the tool reads two specific files and lists agents if the slug is not found. This is adequate, though it does not explicitly state read-only nature, which is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus an Args section, all front-loaded with the purpose. Every sentence serves a purpose, with no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 an output schema, the description covers the action, parameter meaning, and edge case. The output schema covers return values, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides essential meaning: 'Folder name of the agent' with examples ('archivist', 'librarian'). This adds significant value beyond the schema's bare parameter definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Load an agent's system prompt and contract', which is a specific verb and resource. It further specifies the exact files read and the behavior when the agent is not found, distinguishing it from sibling tools like get_context or get_research_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_context or get_working_memory. The description only mentions the fallback listing of agents but does not set usage boundaries or prerequisites.
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 disclose behavior. It describes a read-only load operation returning a summary, but doesn't mention side effects, auth requirements, or rate limits. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is relatively concise with version header, purpose, usage note, and arg spec. Could drop version number without loss, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, output schema exists), the description covers purpose, when to use, and parameter meaning. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'level' with enum values explicitly listed in description, compensating for 0% schema coverage. Provides clear actionable options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool loads a constitutional policy for agent context, with specific verb and resource. It distinguishes itself from other get_ tools by focusing on governance rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains when to use: prepend to system context for shared policy enforcement. No explicit exclusions or alternatives, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It describes input and returns but does not explicitly state that the tool is read-only, non-destructive, or safe to call. It adds context on the return format but lacks these behavioral disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: one sentence for purpose, plus structured Args and Returns. No wasted words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one optional param, output schema present), the description is fairly complete. It explains purpose, parameter, and return summary. It could mention prerequisites like requiring a course build to exist, but that is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the 'slug' parameter and its default behavior (empty lists all active builds). This adds meaning beyond the schema alone, though it could be more precise about slug format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'current status of a course build', distinguishing between querying a specific course or all active builds. This differentiates it from siblings like 'start_course_build' and 'publish_course'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool: to get the status of a course build. It explains the default behavior when slug is empty. It does not explicitly mention when not to use or name alternatives, but the context is clear.
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 bears full burden. It reveals retrieval of briefs with filters but does not explicitly state it is read-only, mention ordering, pagination beyond limit, or potential 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with a clear intro and a bullet-style parameter list. Every sentence adds value, no fluff, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters fully documented and an output schema present, the description covers input needs comprehensively. It does not require additional context about returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides clear semantics for all 4 parameters: limit (max number, default 10), source_type (filter values), domain (examples given), since (ISO date). This fully compensates for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Retrieve recent news briefs from the database' with a specific verb and resource, and the sibling tools (e.g., get_ideas, get_journal) are distinct, making the purpose clear and distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Parameter details imply usage context but no explicit guidance on when to use this tool vs alternatives, no exclusions, and no mention of 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?
No annotations are provided, so the description carries the full burden. It discloses that results are returned in newest-first order, which is a behavioral trait. However, it does not mention other relevant behaviors such as whether the tool returns an empty list if no topic matches, any rate limits, or authentication requirements. The description is adequate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line stating the purpose and one line for the parameter with an example. No wasted words. The purpose is front-loaded immediately, allowing the agent to quickly understand the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, an output schema exists (so return format is covered elsewhere), and the description succinctly covers what the tool does and how to use the parameter. It is complete for a simple read-only retrieval tool. Some may argue it could mention that it filters from memory entries, but that is implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'topic' parameter as 'Topic tag to filter by' and provides concrete examples ('metis-setup', 'phd-research'), adding meaning beyond the schema's simple type definition. This helps the agent understand what values to supply. It does not list all possible values, but given no enums, it is sufficiently informative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return all memory entries tagged with a specific topic, newest first.' This specifies the verb ('return'), the resource ('memory entries tagged with a topic'), and the ordering ('newest first'), distinguishing it from siblings like search_memory (which likely does full-text search) or list_recent_memory (which may not filter by 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage example (e.g., 'metis-setup', 'phd-research') and implies when to use this tool: when you need to retrieve memory entries filtered by a specific topic tag. However, it does not explicitly state when not to use it or mention alternatives, though these are implied by sibling tool names.
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 disclose behavioral traits. It notes the read-only nature ('Retrieve') and the limit of 20 entries when no session is given, but lacks details on output format, permissions, 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with no unnecessary words. It front-loads the purpose and efficiently explains the parameter in a separate line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of an output schema, the description covers the core functionality adequately. It could mention the output type, but the output schema likely fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains the parameter's purpose and behavior ('Pipeline session ID. Leave empty to get the 20 most recent entries across all sessions.'), adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve working memory for a session' with a specific verb and resource. It distinguishes two use cases (with and without session_id), setting it apart from siblings like 'set_working_memory' and 'search_session_memory'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly guides when to use: provide session_id for a specific session or leave empty for recent entries. However, it does not explicitly mention when not to use or compare to 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 must carry the full burden. It describes the tool as loading and returning a context block, implying a read operation, but does not explicitly state it has no side effects or require permissions. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs plus an args line—no fluff. Every sentence adds value, and the structure is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low schema coverage and no annotations, the description explains the return value (structured brief with three components) and usage context. The presence of an output schema reduces the need to detail return format. Nearly complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter with no description (0% coverage). The description adds meaningful context by providing an example ('e.g. "hat-dashboard", "article-1"') and clarifying it is a 'project slug', which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Load' and resource 'full context block for a project'. It explicitly states what it returns (context_doc, recent session history, next step formatted as a structured brief), clearly distinguishing it from siblings like get_context or get_project_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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using it 'at the start of any work session on a specific project so Claude has full background.' This provides clear context for when to use the tool, though it does not explicitly mention 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?
No annotations provided. Description lists output but does not disclose behavioral traits such as read-only nature, permissions required, or side effects. Minimal transparency beyond output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and front-loaded with action and bullet points for output. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and presence of output schema, the description adequately explains the tool's purpose and output components. Could elaborate on return value types but sufficient for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100%. Description adds meaning by detailing the report's contents, exceeding the baseline score of 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it generates a health report for the memory palace with specific output components (entry counts, topic coverage, gaps, duplicates, provenance). Distinguishes from sibling tools that add or retrieve individual memory entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for assessing memory health but does not explicitly state when to use vs alternatives like search_memory or get_topic_memory. Context is clear but lacks exclusions or alternative recommendations.
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; description discloses it records a signal, is non-destructive, and returns confirmation or error. Doesn't detail side effects or auth needs, but sufficient given simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with paragraphs and an Args section. Front-loaded with purpose. Each sentence provides useful information, though slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all 5 parameters, return value, and error case. Output schema exists. Completeness is good for a moderate-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Each parameter is thoroughly documented in the description text, including valid values for event_type, defaults, and optionality. Adds significant value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States 'Record one signal about how you think and work' with a clear verb, resource, and purpose. Distinguishes from sibling get_thinking_profile by mentioning it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance: 'Call it whenever a meaningful preference moment occurs.' Lists event types and references get_thinking_profile. Lacks explicit when-not or comparison to reset_thinking_profile.
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 burden. It discloses key behaviors: deletes records and tasks, optionally deletes folder with safety check. However, it does not mention irreversibility, auth requirements, or return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise with three focused sentences plus Args list. Every sentence earns its place: purpose, deletion scope, and parameter details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate complexity, the description covers main behavior and parameters. Output schema exists but not shown; description could mention irreversibility and return value for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates by explaining both parameters: project_id as the ID to remove and delete_files as boolean with default False and safety condition. This adds meaning beyond schema titles, though project_id format is not detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a project from Metis entirely' with specific verb and resource. It explains what gets deleted (project record, tasks, optionally folder) and distinguishes from siblings like archive_project which implies temporary state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use (permanent removal) and includes a safety check for file deletion. However, it does not explicitly compare to alternatives like archive_project or unarchive_project, which would help the agent 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 provided, but description discloses key behavior: fetches RSS feeds, adds to news_briefs, deduplicates by URL for safe re-runs. Does not cover rate limits or failure handling, but sufficient given the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with critical information front-loaded. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, output schema presence, and 100% schema coverage, description covers main behavior. Could mention return format but output schema likely handles that. Minor gap: no mention of error handling for feed failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0 parameters, so description correctly omits parameter details. Baseline of 4 applies as no param info needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool fetches RSS feeds and adds items to news_briefs, listing specific sources (WHO, CDC, PLOS, Anthropic). This distinguishes it from sibling scanning tools like scan_literature or scan_pubmed_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for aggregating news from these sources but does not explicitly state when to use vs alternatives or when not to. The deduplication note hints at idempotent usage but lacks exclusions.
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 disclose all behavioral traits. It clarifies ephemeral, session-scoped behavior and non-indexed nature, but omits side effects like overwriting existing keys, size limits, or error handling. Output schema existence may cover return values, but 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with five sentences. It is front-loaded with the action, followed by purpose and parameter details in a clear, structured format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with three required parameters, the description covers purpose, usage context, and parameter semantics. It lacks constraints on key length or value size, but output schema likely handles return values, making it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), but the description's 'Args' section adds meaning: session_id source, key as variable name, value as any text/JSON. This compensates well, though value format could be more precise.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write a key/value pair to the current session's working memory,' providing a specific verb and resource. It implicitly distinguishes from sibling 'get_working_memory' and other storage tools by focusing on write and ephemeral nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that working memory is ephemeral and for mid-pipeline state, contrasting with long-term searchable memory. It advises use cases like intermediate results, but does not explicitly name alternative tools 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.
- 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 discloses that the tool writes to 'system/thinking-profile.yaml', lists the computations performed (connection_preferences, preferred_idea_sources, agent_feedback), and states it is safe to call multiple times. This provides good behavioral context, though it could elaborate on potential side effects or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the first line stating the action, followed by bullet points of computations, and a final note on file writing and safety. Every sentence adds value, and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool does (recompute from last 90 days), what it computes (three metrics), and that it writes to a YAML file. It is safe to call multiple times. Given that an output schema exists (as per context), the description does not need to detail return values. It is complete enough for an agent to understand the primary behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter information. The baseline for no parameters is 4, and the description meets this by not introducing unnecessary confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Recompute and update', the resource 'thinking profile', and the scope 'from the last 90 days of events'. It distinguishes itself from sibling tools like 'get_thinking_profile' (read-only) and 'reset_thinking_profile' (reset) by describing its update and computation behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes 'Safe to call multiple times', which implies it can be used repeatedly. However, it does not explicitly state when to prefer this tool over alternatives like 'get_thinking_profile' or 'reset_thinking_profile', nor does it mention any prerequisites or when to avoid calling 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?
Without annotations, the description explains the merging behavior but lacks details on side effects, permissions, validation, or return values. The existence of an output schema is not leveraged in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an arg list, front-loaded with the action and resource. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and merging behavior. It does not address error handling or validation but is adequate given the tool's simplicity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the parameter description adds value by stating that yaml_content should be a complete YAML string from the wizard. It could be improved with structural requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Write' and the resource 'user-config.yaml', and specifies it is the full config produced by the wizard. This distinguishes it from sibling tools like get_user_config and write_user_preferences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for writing the full config produced by the first-run wizard and mentions merging behavior to preserve contexts. However, it does not explicitly state when not to use this tool or list 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 provided, the description must bear the burden of behavioral disclosure. It states that the tool merges the provided JSON into existing preferences, which is a key behavioral trait. However, it does not disclose other important aspects such as whether the operation is destructive, required permissions, or error handling. The merge behavior is helpful but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point, consisting of two sentences plus a parameter explanation. Every sentence adds value: the first sentence states the purpose, the second explains the key behavioral trait (merge), and the third clarifies the parameter. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 an existing output schema (which need not be described per rules), the description covers the core functionality and parameter semantics adequately. It explains the merge behavior and provides example keys, making it complete enough for an agent to use correctly. Minor omission: no mention of the return value, but the output schema compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description is essential. It includes an 'Args' section that explains json_content as a JSON string with example keys (news_topics, journals, etc.), adding significant meaning beyond the schema's bare type definition. While it does not define the exact structure, the examples improve usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes 'user-preferences.json' produced by the first-run config wizard. The verb 'write' and the specific resource are explicitly mentioned, making the tool's purpose unmistakable. It also distinguishes from sibling tools like write_user_config by targeting preferences specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: it is meant for incremental saves of the first-run config wizard to avoid overwriting earlier sections. This implies when to use the tool effectively. However, it does not explicitly mention when not to use it or list alternative tools, so it falls short of a perfect score.
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 burden. It explicitly states idempotency and details the actions: creating semantic memory nodes with deduplication and pruning working memory older than 7 days, which sufficiently discloses 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a front-loaded summary sentence followed by a clarifying paragraph. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers the core behavior but does not explain prerequisites (e.g., existence of reflexions) or potential return values. The output schema likely covers return info, so it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by clearly explaining the parameters: '>= min_count times in the last `days`'. This adds semantic meaning beyond the schema's default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('distil' and 'prune') and clearly identifies the resource ('recurring reflexion themes into semantic memory' and 'working memory'). It distinguishes itself from sibling tools like aggregate_reflexions_tool by specifying a nightly consolidation process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for nightly self-improvement consolidation but does not explicitly state when to use this tool versus alternatives like aggregate_reflexions_tool or consolidate_session_memory. No exclusions or prerequisites 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?
With no annotations, the description must fully disclose behavior. It explains the creation process and layer constraints but does not mention idempotency, overwrite behavior, or error handling for duplicate slugs. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief purpose statement, a step-by-step usage note, and a clear parameter list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers creation steps and parameter details. An output schema exists, so return values are not needed. However, it does not mention success/failure signals or what the tool returns, leaving slight ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by detailing each parameter: slug (URL-safe identifier), name (human-readable), description (coverage), layer (custom vs built-in), and folders (list of subfolder paths). Examples further clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Register a new custom knowledge database layer.' It uses a specific verb and resource, and it differs from sibling tools like build_pdf_knowledge_db (indexing) and list_knowledge_databases (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit steps are provided: after creating, add PDFs and call build_pdf_knowledge_db. It also explains layer numbering (4+ for custom, 1-3 for built-ins), guiding appropriate usage. However, it lacks explicit when-not-to-use scenarios.
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 burden. It mentions authentication, automatic URL prefix handling, and return format (JSON as text). However, it does not disclose potential side effects of write operations (POST/PUT), rate limits, or error behavior, which are important for a tool that can modify data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, parameter explanations, and examples. It is front-loaded with the core action. While thorough, it could be slightly more concise (e.g., combining explanation and examples), but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, an output schema (though not shown), and no annotations, the description is comprehensive. It explains all parameters, provides examples, and specifies behavior (authentication, prefix handling, return format). It covers the necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides full parameter documentation via an Args section, explaining endpoint (relative path), params (dict), method (default GET), and body (serialized for POST/PUT). It also gives multiple examples. This adds significant value beyond the bare input schema, which has 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Make an authenticated API call to the configured DHIS2 instance.' It specifies use cases like metadata validation and data element lookup, and gives concrete examples. This is a specific verb+resource definition that distinguishes it from sibling tools like dhis2_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool ('live metadata validation, data element lookup, indicator queries, and data quality checks'). It provides usage examples and parameter guidance, but does not explicitly state when not to use it or compare with alternatives like dhis2_metadata, which would be ideal.
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 the tool writes a file to 'outputs/exports/' and returns its path plus a preview. However, it does not state whether the tool is read-only or if it modifies the library, leaving some 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear top-level purpose, a contextual sentence, and a bullet list of parameters. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the output (file path and preview), mentions a sibling format option, and explains all parameters. However, it omits prerequisites (e.g., library must exist) and idempotency details, which are minor gaps for an export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (coverage 0%), but the description provides clear explanations for all 5 parameters, including defaults and the role of each filter. This fully compensates for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the verb ('Export') and the resource ('library references as a citation file (BibTeX)'). It distinguishes from siblings by mentioning that RIS format is available via 'mine_references', providing 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to produce a .bib file for Word, LaTeX, etc.) and notes that RIS is available via a sibling tool. However, it does not explicitly list when not to use it or more detailed alternative conditions.
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 mechanism (runs a fixed question set over PaperQA2, assembles a markdown table), and notes the prerequisite (scope must be built with index_library_pdfs()). No destructive actions implied, and the behavior is well described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three focused paragraphs: purpose, output format and use case, parameter details. It is front-loaded and efficient, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, output format (markdown table with citations), parameter details, and prerequisite (indexing). With an output schema present (though not shown), the description is sufficient for an agent to understand the tool's behavior and requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining all three parameters in the Args section: topic (subject), fields (optional comma-separated, default set), scope (index, with build note). This adds clear meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it extracts a structured, cited evidence brief from the PDF library using a fixed question set, producing a markdown table with citations. This distinguishes it from sibling tools like search_literature or ask_library by focusing on structured extraction for systematic-review scaffolding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the use case ('systematic-review scaffolding') and explains parameters (topic, fields, scope) but does not explicitly state when not to use it or mention alternatives among siblings, though the context is clear.
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 explains that the tool stores a placeholder row in daily_insights and that the Metis agent performs the actual synthesis. It does not detail side effects like overwriting behavior, idempotency, or required permissions. Since no annotations are provided, the description carries the full burden for behavioral transparency, but it is adequate for a tool with no parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence immediately states the purpose, followed by a clear bulleted list of gathered data. It efficiently covers what the tool does, its side effect, and the return value without any extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear output), the description is complete. It explains the data sources, the placeholder storage, and the relationship to get_daily_insight. The return value is described, and the presence of an output schema is noted in the context, so the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description explicitly states 'Takes no arguments.' This adds clarity beyond the schema, confirming there are no inputs needed. With 100% schema description coverage, the baseline is 3, but the explicit statement earns a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool assembles recent activity into context for a daily insight. It specifies the exact sources and timeframes (e.g., last 7 days of agent_runs, last 3 days of news_briefs). It distinguishes itself from the sibling tool get_daily_insight by explaining that this tool prepares the context while get_daily_insight retrieves the stored 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it gathers raw material for the daily insight and instructs users to read the stored result later with get_daily_insight. However, it does not explicitly state when not to use this tool or mention alternative approaches, leaving some room for ambiguity.
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 reads the consent_ledger and returns a JSON text block with specific fields, indicating it is a read-only operation. However, it does not mention potential side effects, idempotency, or access restrictions, though these are minimal for a read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with a clear purpose sentence, followed by a paragraph detailing the return content, and ends with parameter documentation in a consistent format. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no annotations, but with an output schema implied), the description is complete. It explains the tool's function, the parameter, and what the output contains, including specific fields. There is no missing information needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant value by explaining the 'limit' parameter: 'Number of most recent ledger rows to return, newest first (default 30).' This clarifies the purpose and default behavior beyond the schema's bare specification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves recent consent events from the audit ledger, specifying the verb 'retrieve' and the resource 'consent events'. It distinguishes itself from the sibling tool 'log_consent_event' which writes to the ledger, thus clarifying its read-only purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reviewing or reporting on consent data and mentions it reads the ledger that 'log_consent_event' writes to, but it does not explicitly state when to use this tool versus alternatives or when not to use it. Usage is inferred rather than explicitly guided.
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. 'Retrieve' implies read-only and no side effects. While it doesn't mention pagination or ordering, the tool is simple with zero parameters and an output schema, so the behavior is sufficiently disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no unnecessary words. It efficiently communicates the tool's action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, has output schema), the description is complete. It states the core action without needing to detail return values or additional context, as the output schema covers the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and description coverage is 100% (no params). The description doesn't need to add parameter information, and the baseline for zero params is 4. No additional value is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve all glossary terms' clearly states a specific verb ('Retrieve') and resource ('all glossary terms'), and it distinguishes from the sibling 'add_glossary_term' which performs a different 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use or when-not-to-use guidance. However, the tool is straightforward and the usage is implied: use it to get all glossary terms. No sibling tool overlaps with this retrieval purpose.
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 states entries are returned newest first and optional date filtering, but lacks explicit read-only confirmation or discussion of rate limits/auth. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: brief intro, usage context, parameter explanations. Every sentence adds value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description covers purpose, usage, and parameters. Minor missing details like pagination or exact return format, but overall complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains both parameters: date_from format and behavior, limit meaning and default. Adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists journal entries, newest first, which is a specific verb+resource. It distinguishes itself from sibling tools like add_journal_entry (adds) and other list 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: looking back over dated entries, rebuilding context. It does not explicitly say when not to use it or compare to alternatives, but the context is 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 discloses sorting by most recent first, and the returned fields (agent slug, rationale, diff summary). It does not mention any safety concerns or side effects, but for a read-only list tool, this is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the purpose, the second details output ordering and content. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the presence of an output schema, the description sufficiently explains the tool's behavior and return value. No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description adds no parameter info, which is appropriate; baseline 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists skill improvement proposals awaiting review, with a specific verb and resource. It distinguishes from siblings like approve_proposal, reject_proposal, etc., by focusing on listing pending ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing pending proposals before approval/rejection, but it does not explicitly state when to use it versus alternatives or provide exclusion 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?
With no annotations, the description carries the full burden. It discloses that the tool reads PDFs, stores only the first 4000 characters, updates the abstract, and is incremental (only processes unindexed files). This covers key behavioral traits without 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences plus an args list) and front-loaded with the main action. It is efficient but could be slightly tighter; nonetheless, it earns its keep.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no annotations, output schema exists), the description covers sources, storage location, incremental behavior, and scope. It does not need to explain return values due to output schema. Missing mention of performance or limitations, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage (no descriptions for parameters). The description compensates by explaining the 'scope' parameter values: 'literature', 'zotero', and 'all', with clear mappings. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Extract and index full text from all PDFs in the Metis library.' It specifies sources (inputs/literature/ and Zotero storage) and what is stored (first 4000 characters, updates abstract). This distinguishes it from siblings like 'search_literature' or 'scan_literature'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use: for incremental indexing of PDFs, with scope options. It does not explicitly state when not to use or mention alternatives, but the purpose 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 are provided, so the description carries the full burden. It discloses the returned data fields but does not confirm read-only status or any potential side effects. It is straightforward but lacks extra 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first defines the tool's action, the second provides usage guidance. No unnecessary words, excellent efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema (not shown but present), the description covers the essential information—listing entities with claim count and last update. It is complete for its intended overview purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% description coverage (vacuously). The description adds no parameter info, which is appropriate since there are none. Baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'entities in the research timeline', and includes what information is provided ('claim count and last update'). It also implicitly distinguishes from sibling tool 'query_research_timeline' by suggesting using this before drilling into a specific entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using this tool to get an overview before drilling with 'query_research_timeline()', providing clear context for when to use it. No explicit when-not-to, 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?
With no annotations, the description carries full burden. It describes the checks performed and that it returns a structured report, but doesn't state that the tool is read-only or non-destructive, nor does it mention any side effects or authorization 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences cover purpose, checks, and usage. Every sentence adds value with no redundancy. Well-structured for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an existing output schema, the description fully covers what the tool does and when to use it. No gaps identified for a health check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (no params to describe). The description adds value by listing what the health check verifies, which indirectly covers the expected output fields, earning a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run a one-screen health check on Metis.' It lists specific components verified (Python version, SQLite, API key, etc.), distinguishing it from sibling tools, none of which are health check 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use when:' section provides explicit scenarios: troubleshooting, pre-publishing, and post-pull verification. While it doesn't mention when not to use or alternatives, the guidance is contextually clear and 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?
With no annotations, the description must fully disclose behavior. It mentions the tool is timestamped and preserves chain of reasoning across sessions via supersedes_id. However, it does not explicitly state that it creates/modifies data, requires permissions, or has any 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and use cases, followed by a well-organized Args list. Each sentence is relevant and concise. No redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (2 required, 5 with defaults) and no annotations, the description covers all parameters and explains behavior (timestamping, chaining). It does not mention the return value, but an output schema is provided (not shown). Slight gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the tool description includes a detailed Args section covering all 7 parameters. It provides context on usage (consistent naming for entity, 1-3 sentences for claim, examples for evidence and source_ref, allowed values for confidence and source_type, and how to use supersedes_id). This greatly adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records 'a timestamped research belief or finding about an entity.' It specifies when to use it (conclusion, update, evidence) and distinguishes from sibling tools by focusing on research findings and timeline preservation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('reach a conclusion, update a previous belief, or encounter evidence that changes your view') and provides guidance on consistent naming for the entity. It doesn't specify when not to use it or list alternatives, but the context is 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 carries the burden. It discloses that re-registering is idempotent (replaces previous dictionary matched on dataset_name + project_id), describes the return value, and states error behavior. It does not detail side effects, but the behavior seems straightforward 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-line summary, a clarifying paragraph, then a clear bullet list of arguments, and a return description. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 4 parameters (including a complex array), the description covers purpose, arguments, return, and idempotency. It lacks only minor details like potential error scenarios beyond empty variables, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides detailed explanations for all 4 parameters. It clarifies the variables array format (string or object with name required), the role of project_id in idempotency, and provides examples. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a data dictionary for a dataset, storing per-variable metadata like name, type, and labels. It differentiates from sibling tools by focusing specifically on dictionary registration and mentions idempotency, which clarifies its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to record variable definitions for a dataset, but it does not explicitly state when to use this tool versus alternatives (e.g., add_glossary_term, record_dataset_treatment). No exclusions or contextual guidance are 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?
No annotations are provided, so the description carries full burden. It discloses that by default only the index is removed, file deletion is guarded to paths within PKM root, and returns confirmation or error messages. It does not detail permissions, but the safety guard is mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief summary followed by details on behavior, parameters, and returns. It is front-loaded and clear, though could be slightly more concise without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, behavioral details, safety, and return value. Given that an output schema exists (context signal), the return description suffices. For a 2-parameter tool with no annotations, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains both parameters: 'relative_path' as primary key, and 'delete_file' with default False and safety check. This adds meaning beyond the schema, though the format of relative_path is not specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes a library item from the Metis index, optionally deleting the file. It uses a specific verb 'remove' and resource 'library item', and distinguishes itself from the sibling tool 'archive_library_item' which hides rather than removes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use this tool versus 'archive_library_item' (hide instead of remove), and explains the optional file deletion. However, it does not explicitly state when not to use it (e.g., for items that shouldn't be removed).
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 full burden. It discloses that source files are written as YAML in a specific path and the build advances, but does not mention overwrite behavior, validation, required permissions, or error handling. This provides some but not comprehensive behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (~100 words), well-structured with a header, usage note, and argument list. Every sentence serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the step context, input requirements, and action. Although an output schema exists, the description does not mention return values, which is acceptable per guidelines. It lacks any mention of error conditions or side effects but is still fairly complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description is essential. It defines both 'slug' and 'sources', includes required fields for each source dict ('title' plus one of url/file_path/doi'), and provides an example. This adds high value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save', the resource 'harvested source metadata', and the context 'for a course'. It positions it as Step 3 in a build process, distinguishing it from sibling tools like save_course_curriculum or save_course_outline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call this after the Content Harvester has collected materials and that it advances to Step 4. While it does not list negative cases or alternatives, the step context provides clear usage 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?
With no annotations provided, the description fully discloses that it uses free NCBI E-utilities with no API key, inserts results into news_briefs, and is safe for daily scheduling. It does not detail rate limits or error handling, but 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary, a context paragraph, and an Args list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description sufficiently covers inputs, data destination, and usage cadence. Missing details like error handling or rate limits are minor gaps, but the overall completeness is high for a simple scanning tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description's 'Args' section provides detailed semantics for each parameter: query's multi-level fallback, reldate's meaning, and max_results' default. This compensates entirely for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Scan PubMed for recent papers matching a query', specifying the exact resource (PubMed) and action. It is distinct from siblings like scan_news or scan_openalex, which target different sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is 'Safe to call daily from the morning scan scheduler job', providing a clear use case. However, it does not explicitly state when not to use this tool or compare it to alternative scanning tools like scan_literature or scan_openalex.
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 internal actions: reads the tracked_files table, checks file modification times, and updates last_scanned timestamps. With no annotations, this provides adequate transparency for a simple scan tool, though it omits potential side effects beyond timestamp updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence states the primary purpose, and the second elaborates on internal steps. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema (implied but not shown), the description fully explains the tool's job, behavior, and side effects. No additional information is needed given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description adds meaning by explaining the tool's functionality. Schema coverage is 100% trivially. The description compensates for lack of parameters by describing what the tool scans and updates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (scan) and resource (tracked files) and specifies the outcome (report which have changed). It distinguishes from sibling tools like add_tracked_file and remove_tracked_file by focusing on scanning existing tracked files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking changed tracked files, but provides no explicit guidance on when to use this tool versus alternatives like scan_project_folder or scan_folder_for_intent. No when-not-to-use or exclusions 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 states the action and parameter meanings but does not disclose any side effects, needed permissions, rate limits, or return behavior. For a simple toggle, it is minimally sufficient 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a clear args list. It is front-loaded with the main action, and no superfluous text exists. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 nested objects, has output schema), the description covers the core behavior and constraints. However, it does not describe the return value or confirm that the output schema documents the result. Slightly incomplete but largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains both parameters: name (context name to toggle, must exist) and active (boolean to activate/deactivate). This adds essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Activate or deactivate a specialist context.' The verb 'toggle' paired with 'specialist context' is specific and differentiates from sibling tools like add_specialist_context (create) and list_contexts (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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite: name must exist in specialist_contexts. It implicitly distinguishes from add_specialist_context by mentioning existence, but does not explicitly explain when not to use or list alternatives. Slight lack of explicit 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 exist, so the description carries full burden. It discloses that 'name' is used as a unique key (determining add vs update) and specifies the birthday format. Missing are permissions, side effects, or error handling, but for a simple CRUD tool this is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a two-line summary followed by a bullet-like parameter list. No redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers the essential behaviors and parameter semantics. Minor additional context (e.g., what happens if name is missing) would improve, but currently sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaningful context for each parameter: name as unique key, notes, role, birthday format. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add or update') and the resource ('contact record'). The tool name 'update_contact' aligns well. Among siblings, there is 'get_contacts' but no other contact mutation tool, so it distinguishes sufficiently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through parameter explanations but lacks explicit guidance on when to use this tool versus alternatives or when not to use it. The unique key note helps, but no conditions or exclusions are stated.
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 so description carries full burden; it explains the action (integrity_check) and return format (JSON with status and table count). Minor omission: no mention of error handling or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences plus structured Args/Returns; no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter verification tool with output schema available, the description covers purpose, input requirements, and output format adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter is described with format constraints (full path, .sqlite, unencrypted) compensating for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs SQLite integrity_check on a backup file, distinguishing it from siblings like backup_db, restore_db, encrypt_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides prerequisite (unencrypted .sqlite) but lacks explicit guidance on when to use versus alternative backup 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?
No annotations are provided, so the description must carry the full burden. It explains that entries are reviewed for self-improvement, but does not disclose side effects, auth requirements, or whether it overwrites entries. For a read-like write operation, it is minimally 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured clearly with a title line, a usage paragraph followed by a parameter list. It is concise (approx. 100 words), front-loads the purpose, and has no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (2 required) and presence of an output schema, the description covers purpose, usage timing, and parameter semantics. It provides adequate context for an AI agent to invoke the tool correctly, though it omits the return value format (covered by output schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the tool description provides detailed parameter explanations (e.g., 'went_well: What went well in this run (1-2 sentences)'). This adds significant meaning beyond the schema titles and required list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Record an agent self-critique entry to the reflexion_log.' It specifies the stage (Stage 11) and the context (end of every agent run). This distinguishes it from similar tools like log_agent_run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Called at the end of every agent run to capture experience' and mentions the weekly Coach loop review. It provides clear context but does not contrast with siblings like aggregate_reflexions_tool or log_agent_run.
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: writing to skill.md, creating a backup first, and marking the proposal as approved. It does not mention edge cases like double-approval, but the main effects are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences plus an args line—every sentence is essential. No fluff, front-loaded with the main verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description covers the purpose, input, and side effects. It could mention the return value but an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description adds meaning: 'The numeric ID from get_pending_proposals()' tells the agent the source and type, beyond the schema's integer definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: approve a pending skill improvement proposal and apply it by writing to skill.md. It names the resource (skill.md) and distinguishes from siblings like reject_proposal and get_pending_proposals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent that proposal_id comes from get_pending_proposals(), implying the tool is used after retrieving pending proposals. While it doesn't explicitly exclude other contexts, the purpose is 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 provided, the description effectively discloses the mutation behavior (status update), that the item is kept in DB, searchable, and hidden from default view. It does not cover permissions or idempotency, but overall 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences: a one-line summary, a line explaining the effect, and an Args section. Front-loaded with the main purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 an output schema (presumably returning success/failure), the description covers the effect, the parameter, and persistence behavior. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter `relative_path` is described as 'the relative_path primary key in library_seeded table', adding critical context beyond the schema's type-only definition (string). This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: archive a library item by setting status to 'archived'. It distinguishes from hard deletion and from archival of other resources like projects. The verb 'archive' and resource 'library item' 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 Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for items that should be kept but hidden from default view, but it does not explicitly state when to use this tool over alternatives like `remove_library_item`. No prerequisites or exclusions 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 discloses recursive walking, recognized extensions, and the max_files safety limit, but does not cover idempotency, error handling, or authentication needs. The description adds value beyond the schema but is not comprehensive for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using four well-structured sentences: main purpose, details on recursion and extensions, usage instruction, then parameter list. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (recursive folder walk, extension list, three parameters) and the presence of an output schema (not shown), the description is fairly complete. It explains what the tool does, how to use it, and parameters. Missing details like error handling or idempotency are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides clear explanations for all three parameters: folder_path (absolute path), label (short label), and max_files (safety limit with default). This adds significant meaning beyond the schema's type/default info, compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool registers all relevant files in a project folder so Metis can read them, specifying the verb 'register', the resource 'project folder', and the outcome 'files added to tracked_files table'. It distinguishes from sibling tools like read_file by providing post-use instructions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this once per project; after that, use read_file() to read any individual file', providing clear when-to-use and when-not-to-use guidance with an alternative named.
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 the tool creates a DB record, CLAUDE.md, and links Claude Desktop, and mentions automatic linking of Claude Desktop config. This provides good behavioral insight, though it could note safety aspects like idempotency or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short paragraphs: purpose, context, parameter list. It is front-loaded with the key action, no redundant sentences, and every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is an output schema (not shown but noted as present), the description does not need to explain return values. It covers all six parameters sufficiently, though it could mention prerequisites (e.g., folder existence) or error scenarios. Overall, it is complete for a creation tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add value. It provides a bullet list with explanations for each parameter, including behavior like auto-detection of description when scan_type is not 'none'. This adds meaning beyond the schema's bare JSON types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create a project with full Metis integration: DB record, CLAUDE.md, Claude Desktop.' This is a specific verb+resource+scope, and it distinguishes this tool from siblings like 'create_project' by emphasizing the full integration aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'This is the unified project creation tool used by all installers and the dashboard.' This gives context for when to use it, but it does not explicitly mention when to avoid it or use alternatives like 'create_project'. The guidance is clear but lacks exclusions.
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 behavioral burden. It discloses that the tool runs four scans, adds new items to news_briefs, registers PDFs, flags unprocessed items, and reports changed files. It explicitly states no LLM calls and safety. However, it does not mention idempotency or potential conflicts between scans.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the purpose, and uses a clear bullet list for the scans. Every sentence adds information, and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool triggers multiple scans and has an output schema (not shown), the description covers what each scan does and that a combined report is returned. It is sufficient for an agent to understand the tool's scope, though details about the report format are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema coverage is 100%, so baseline 4 applies. The description adds value by explaining what the tool does without needing to describe parameters, listing the scans that are executed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: running all Metis update scans in sequence and returning a combined report. It lists the four specific scans (news feeds, literature folder, inbox, tracked files), making it distinct from sibling tools that perform single scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it is safe to run at any time and involves no LLM calls, giving clear context. It implies using this tool for a full update versus individual scan tools, but does not explicitly state when to prefer this over the specific scan 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, the description effectively conveys that the tool is a read-only query of library stats, taking no arguments and returning a formatted summary. It mentions potential dependence on Zotero sync but does not indicate any destructive actions. A slight improvement would be explicitly stating it does not modify the library.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief introductory sentence, usage context, and a list of return values. It is informative without excessive length, though a minor reduction in detail about return values could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema is present, the description covers all necessary aspects: purpose, usage context, what it returns, and related tools. No gaps remain for an agent to effectively select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description reinforces that it takes no arguments, which aligns with the empty input schema. No further parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool summarizes the literature library, providing a quick overview of total papers, breakdown by source and item type, recent references, and Zotero sync state. It distinguishes itself from siblings like search_library and sync_zotero_library by focusing on summary statistics rather than searching or syncing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before searching or citing to gauge the library's size and currency. It also mentions pairing with search_library and sync_zotero_library, indicating complementary tools. While it doesn't list specific scenarios to avoid, the guidance is clear enough for appropriate usage.
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 fallback to default structure when the file is missing, which adds transparency. However, it does not explicitly state that the operation is read-only or non-destructive, though that is implied by 'Read and return'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no waste. The main action is stated first, followed by a concise fallback note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema exists), the description is complete. It explains what it does, the source file, and the fallback behavior. No gaps remain for an agent to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description adds no parameter information because none is needed. Schema description coverage is 100%, so the description meets the baseline effortlessly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read and return' and the specific resource 'current thinking profile from system/thinking-profile.yaml'. It includes a fallback behavior, making the purpose unambiguous and distinct from sibling tools like update_thinking_profile or reset_thinking_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions fallback behavior but does not provide explicit guidance on when to use this tool versus siblings (e.g., update_thinking_profile, reset_thinking_profile). No alternatives are named or excluded, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It specifies BFS algorithm, max_hops constraint, and return format. Although it doesn't explicitly state read-only nature, the 'find' verb implies it. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single sentence stating purpose, followed by a clean Args list. Every part is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of graph pathfinding and the presence of an output schema to document return values, the description adequately covers input parameters, algorithm, and return format (paths ranked by length). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It provides clear, meaningful descriptions for each parameter, including an example path and default value for max_hops, adding significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds connection paths between two notes via BFS, specifying the resource ('knowledge library notes') and the algorithm. This distinguishes it from ambiguous siblings like 'find_connections'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters but provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (JSON array) and sorting, and implies a read-only operation. No annotations exist, so the description adequately covers behavior without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an arg line: no wasted words, front-loaded with verb and resource, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and an output schema (presumably covering structure), the description is sufficient for a list tool. It explains purpose, parameter, and return format, though details about JSON structure are left to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, but the description adds a clear explanation of the backup_dir parameter and its default value, which the schema alone lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists backup files with specific attributes (size, age, checksum availability), making it distinct from siblings like backup_db or verify_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the default directory and sort order (newest first) but does not explicitly state when to use this tool over alternatives or mention any exclusions.
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 the return format (JSON with extensions, read/write capabilities, library versions). No annotations exist, but the description is sufficient for a read-only, no-side-effect 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences. The first sentence states the purpose, and the second provides key output details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a no-parameter tool. It covers the output sufficiently, and the presence of an output schema further reinforces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description adds value by detailing the output structure. According to guidelines, baseline is 4, and the description goes beyond by specifying the exact information returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists supported dataset formats and installed library versions, using a specific verb and resource. It distinguishes from siblings, as no other sibling tool has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide when to use or when not to use the tool. However, the purpose is self-evident for checking supported formats, but it lacks explicit guidance on 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 the description carries full burden. It discloses that the tool writes to the database for audit/dashboard, can write to session_events, and returns a confirmation message. It does not mention authorization or rate limits, but overall it transparently describes the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary, contextual explanation, and parameter list. It is somewhat verbose due to the parameter docstrings, but it remains clear and front-loaded. Minor reduction in verbosity could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no schema coverage, and an existing output schema, the description explains all parameter semantics, return value, and side effects. It covers prerequisites (session_bootstrap for session_id) and dual behavior. It lacks error handling or edge cases, but for a logging tool, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description provides all parameter semantics. It gives detailed explanations for each of the 9 parameters, including types, defaults, and clarifications (e.g., 'complexity' maps to status column). This adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool logs a completed agent run for audit and dashboard tracking. It specifies the action ('log'), the resource ('agent run'), and the purpose. It distinguishes from siblings like get_agent_runs (retrieval) and session_bootstrap (initialization) by explaining when to call it and the effect on session_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call it after writing an output file, per the output contract.' It also explains when session_id is supplied, it writes a result event. This provides clear context for use, though it does not explicitly mention when not 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?
No annotations are provided, so the description carries the full burden of behavioral transparency. It discloses that the tool returns a JSON with fields probed_content, flagged, and patterns_found, indicating it performs analysis without modifying state. It does not contradict any 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured, using a version header, a one-line purpose statement, a usage guideline paragraph, and clearly labeled Args/Returns sections. Every sentence adds value, and the information is front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, 1 required) and the presence of an output schema (though not shown), the description sufficiently covers its purpose, usage, parameters, and output. It could be considered complete for an analysis tool, though it might optionally mention that it does not modify data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The tool description compensates by explaining both parameters: 'content' as 'The external content to probe' and 'source_label' as 'Human-readable label for logging'. This adds meaningful context beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Probe') and resource ('external tool result') with a specific purpose ('for injection patterns'). It distinguishes from siblings by describing a unique security-related operation, which is not evident in any sibling tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool ('Call this before inserting any externally-sourced content into agent context') and provides concrete examples of such content (web scrapes, RSS items, PDF extracts, YouTube transcripts, GitHub readmes). It lacks alternative tool references or explicit exclusions, but the usage 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?
No annotations provided, so the description carries full burden. It clearly discloses that it marks the course as active, sets progress to 0, and writes a completion note. No contradiction with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs: purpose/behavior, then usage timing, then Args/Returns. Every sentence contributes value. No redundant or wordy content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter and an output schema (though not shown), the description covers purpose, effect, usage timing, and return structure. Could mention prerequisites like requiring all 7 steps to be completed, but it already does. Minor gap: no details on what the completion note contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. The description adds 'The course slug to publish', which only rephrases the schema's 'Slug'. No additional format, examples, or constraints provided. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'publish' and 'finalise', identifies the resource as a completed course build, and describes the specific database actions. Distinguishes well from sibling tools like 'review_course', 'save_course_outline', etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call after all 7 steps are done', indicating the prerequisite context. Does not mention alternatives or when not to use, but the purpose and sibling list provide sufficient 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?
The description discloses key behaviors: returns claims ordered by date, hides superseded by default but can include them. No annotations exist, so the description carries the transparency burden adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence followed by parameter details. It is concise but covers necessary information without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and only three parameters, the description provides sufficient context about returns and options. It explains the temporal evolution and supersedence logic, making it complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No schema descriptions for parameters (0% coverage), but the description explains each parameter thoroughly: entity (partial match, leave empty), since_date (ISO format, on/after), show_superseded (boolean, default False). This fully compensates for missing schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the temporal evolution of research beliefs, with a specific verb and resource. It distinguishes itself from sibling tools by focusing on timeline ordering and superseded claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool returns claims ordered by date and mentions parameter usage. It does not explicitly state when not to use it or alternatives, but the context is clear enough for selection.
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 the read-only nature and file type support, but doesn't discuss error handling, permissions, or encoding. The 'return it as text' is clear, but some behavioral details 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: a main sentence, two bullet points on file types and pre-registration, and an Args section. No wasted words, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description adequately covers core behavior: reads file, returns text, handles various types, no pre-registration needed. It is complete for a file read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description provides thorough parameter documentation in the Args section: path is absolute, max_chars has default and guidance for large files. This adds significant meaning beyond the schema's type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and resource 'file content', and specifies that it works for any text file without pre-registration. This distinguishes it from sibling tools like scan_tracked_files that require tracking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage for reading any text file and advises increasing max_chars for large files. However, it does not explicitly state when to use this tool over alternatives or provide exclusion 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?
With no annotations, the description carries full burden. It discloses the destructive action ('Delete') and idempotency ('Safe to call even if the marker does not exist'), which is adequate for a simple tool. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, usage context, and safety note. No unnecessary words. Front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers core behavior. Though an output schema exists, the description does not explain return value, but for a deletion marker this is a minor omission. Still, overall complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, so schema coverage is 100%. The description adds no parameter info (none needed). Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Delete' and the resource '.first-run marker file', clearly indicating the tool's function. It is distinct from sibling tools which generally do not involve deleting marker files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Called at the end of the first-run wizard after all config files are written', providing clear context for use. It also notes safety even if marker doesn't exist, but lacks explicit alternatives or when-not-to-use. However, for this specific tool, usage 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?
With no annotations, the description carries the full burden. It discloses the write operation: 'Writes to knowledge/courses/{slug}/course.json and advances to Step 5.' This explains the side effects and state progression, which is sufficient for a save 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and includes an Args section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (saving curriculum as JSON), the description covers the key aspects: purpose, when to call, parameters, and side effects. An output schema exists, so return value documentation is not required. It is complete for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that curriculum_json is a JSON object with modules and lessons arrays, adding meaning beyond the schema (which only defines it as a string). It also describes slug as the course slug. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Step 4 — Save the approved curriculum design for a course.' It specifies it should be called after the Learning Architect produces the curriculum, distinguishing it from sibling tools like save_course_outline or save_lesson_draft by its role in a workflow step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use: 'Call this after the Learning Architect has produced the curriculum.' It also mentions the side effect of writing to a file and advancing to Step 5. However, it does not explicitly mention when not to use or suggest alternative 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?
The description explains that the tool searches a pre-built index and returns a synthesized answer with citations. It implies read-only behavior, but since no annotations are provided, the description could explicitly state that no modifications occur. Nonetheless, it offers 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief overview followed by an Args section. It is mostly concise, though the repetition of 'see index_library_pdfs()' could be tightened. 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description covers prerequisites (index must be built), parameter details, and the core behavior. It is complete for a query tool without requiring additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by explaining each parameter in natural language: question ('Natural language question to answer from the library'), top_k (purpose and default), and scope (enumerated values with a note about building the index). This adds substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Answer a question using the user's indexed PDF library via PaperQA2.' It specifies the verb (Answer), resource (indexed PDF library), and method (PaperQA2). This distinguishes it from sibling tools like search_library, which likely performs raw searches without synthesis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use the tool: after building the index via index_library_pdfs(). It mentions the index must be pre-built and references the appropriate sibling tool. However, it does not explicitly state when not to use it or compare to alternatives like search_library.
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 inputs (two JSON strings), outputs (a JSON with specific fields), and implies a read-only comparison with no side effects. It does not mention authentication or rate limits, but the overview is adequately transparent for a comparison tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but effectively covers purpose, arguments, and returns. It is concise without unnecessary words, though it could benefit from bullet points for improved readability. It earns its place with informative content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (mentioned in context), the description does not need to elaborate on return values but still describes the return structure. The two parameters are well-documented, and the tool fits logically among siblings like profile_dataset. The description is complete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully explains both parameters: before_profile as a JSON string from profile_dataset() on the original file, and after_profile similarly for the cleaned file. This adds crucial context beyond the schema's basic type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two dataset profiles and produces a side-by-side diff, listing specific outputs (rows/columns added/removed, null count changes, type changes). This distinguishes it from related tools like profile_dataset (which generates a profile) and clean_dataset (which cleans data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to pass JSON strings from profile_dataset() for original and cleaned files, implying usage after profiling. It does not provide explicit 'when not to use' or alternatives, but the context is clear and sufficient for selecting this tool 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 full burden. It discloses that Mendeley uses BibTeX export and provides source URLs for Zotero credentials. It does not detail side effects like overwriting existing config or error handling, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, a usage sentence, then parameter details in an easy-to-scan bullet style. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not detailed), the description covers essential aspects: purpose, when to use, and parameter semantics. It lacks mention of return values or failure scenarios, but for a configuration tool, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates by explaining each parameter: provider options ('zotero' or 'mendeley'), api_key and user_id for Zotero, bibtex_path for Mendeley. It adds valuable meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Configure the library provider for this Metis installation.' It uses a specific verb (configure) and resource (library provider), and distinguishes from siblings like sync_zotero_library and import_bibtex_library by emphasizing setup and switching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this during setup or when switching reference managers,' providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternatives, which would improve 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, so description carries full burden. It discloses deduplication, writing to DB and markdown files, and the filtering logic. However, it does not describe all behavioral traits such as error handling, overwrite behavior, or performance implications. Adds context beyond schema but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured: a one-sentence summary, followed by an explanatory paragraph, then labeled parameter documentation. No unnecessary words, and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch operation, dedup, dual output) and presence of an output schema, the description covers key aspects: selection criteria, dedup, and targets. It lacks mention of error conditions or behavior with empty runs, but is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates fully. It explains each parameter clearly: n_runs as count of runs to review, min_quality with 'high' vs 'all' distinction. This adds semantic meaning beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Scan recent agent runs and write structured memory entries.' It clearly distinguishes itself from siblings like add_memory_entry (individual addition) or search_memory (search) by focusing on bulk consolidation from agent runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'recent agent runs' and 'high-value work'. It explains the process but does not explicitly state when to use it vs. alternatives like add_memory_entry or when not to use it. Lacks explicit exclusions or direct comparisons.
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 creation of a DB record and its availability for linking and search. No annotations exist, so description carries the burden. It does not mention side effects like duplicate handling, but the behavior is straightforward and non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, focused sentences plus a clear bulleted Arglist. Front-loaded with purpose. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers creation logic, DB effect, and parameter meaning. Does not mention the output schema, but since it exists, the description is not required to detail return values. Could be slightly improved by noting authentication requirements, but not crucial for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description's Args section adds meaningful explanations for each parameter: examples for title, length hint for description, domain examples, and source options. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Register' and the resource 'a new project in the Metis platform', and explains the effect on the DB and UI. It differentiates from siblings like 'create_project_full' by implying this is the standard registration 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context when to call (when researcher confirms permanent tracking), but does not explicitly mention when not to use or compare with the similar sibling 'create_project_full'. The scenario is specific enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers the binary format, passphrase handling (never stored), default output location, and return value. It lacks details on error conditions but is fairly 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then provides format details and Args list. Each sentence serves a purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 params with no schema descriptions and an output schema, the description fully explains inputs, outputs, behavior, and format. No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema coverage is 0%, the description's Args section adds meaning by briefly explaining each parameter's role (enc_path, passphrase, output_path). Could be more detailed but adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool decrypts .enc backups from encrypt_backup, provides the file format, and explains the output behavior. It clearly identifies the action and 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this is the counterpart to encrypt_backup for restoration, but does not explicitly state when not to use it or compare to other restore tools like restore_db. Clear context without exclusions.
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 that the tool returns 'normal' if no policy file exists, which is useful default behavior. No annotations present, so the description adequately covers the main behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, immediately stating the main action and then the default. No extraneous words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (presumably defined), the description fully covers the tool's behavior and default state. No gaps for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds value by explaining the return value and default behavior, exceeding the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current network access policy, distinguishing it from sibling `set_network_policy`. It specifies the return value 'normal' as default, providing precise purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing the policy, contrasting with the sibling tool for setting. No explicit when-not or alternatives, but the simplicity makes it 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?
No annotations are provided, so the description carries the full burden. It discloses that the tool takes no arguments and returns a text line of categories or a message. As a read-only operation, this is sufficient behavioral transparency for a simple 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the first sentence states the core purpose, followed by examples and a reference to the sibling tool, then parameter info and return format. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return format in detail (alphabetical list or 'none defined' message) and references the sibling tool for context. Given the tool's simplicity and the presence of an output schema, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, which sets a baseline of 4. The description explicitly states 'Takes no arguments,' adding clarity beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool returns 'all distinct project categories currently in use' and provides examples ('Article', 'Grant', 'Teaching'). It distinguishes itself from the sibling tool 'set_project_category' by noting it helps offer existing categories before inventing new ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to see existing categories before using 'set_project_category') and implies it's for grouping projects. While it doesn't explicitly list when not to use it, the context is 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 discloses it reads from a specific directory and returns filename, date, and prompt. It is a read-only operation, but could mention any potential side effects or permissions, though for a list tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear purpose sentence followed by a directory note, return fields, and an args list. Every sentence adds value, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (implied by context), the description's mention of return fields is sufficient. It also specifies ordering (newest first). Could mention edge cases like an empty directory, but overall complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds full meaning to the only parameter 'limit', explaining it controls the maximum number of images returned (default 20, newest first). This is valuable beyond the schema which only has type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'generated images in the PKM', and specifies the directory path and return fields. It distinguishes itself from siblings like 'generate_image' (creation) and 'list_folder' (generic listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing recently generated images, and the context of siblings makes it clear when to use. However, it does not explicitly state when not to use or mention alternatives, leaving some room for improvement.
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 the return format (list of dicts with specific fields), ordering ('newest first'), and error behavior ('error' key on failure). No side effects or safety concerns are mentioned, which is acceptable for a read-only list 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: the main action is in the first sentence, with additional context in a few short sentences. It clearly separates Args and Returns sections. No unnecessary words or redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, the description covers purpose, usage context, parameter explanation, return structure, and sibling relationships. It is self-contained and sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'limit' is described as 'Maximum number of summaries to return, most recent first (default 20).' The schema only provides type and default, so the description adds meaningful semantics and usage context, adequately compensating for the schema's lack of property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the most recent session summaries in newest-first order. It explicitly distinguishes itself from sibling tools by naming search_session_memory (keyword search) and save_session_summary (write), making its unique 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('pick up where a previous conversation left off' or 'review recent decisions and topics') and how it complements related tools. It does not explicitly state when not to use it, 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?
No annotations are provided, so the description carries the full burden. It discloses critical behavior: 'The skill file is NOT modified until the user calls approve_proposal().' It also mentions the return value (proposal ID). While it doesn't detail auth needs or rate limits, the non-destructive nature is communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences plus a list of args. It front-loads the purpose, then key behavioral info, then parameters. Every sentence is necessary and no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, no annotations, and an expected output schema (though not provided here), the description covers purpose, behavior, return info, and parameter meanings. It could be more complete by explaining what a skill file is or the format of proposed_content, but it is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains each parameter: agent_slug with an example, proposed_content as the full replacement, and rationale with a length guideline. This adds significant meaning beyond the schema's titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'An agent proposes a change to its own skill file.' It distinguishes from siblings like approve_proposal by noting that the skill file is not modified until approval. The verb 'propose' combined with the object 'skill file' 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (to propose a change) and that the change is queued for human review, implying the alternative of using approve_proposal to effect the change. It does not explicitly state when not to use, but the context is 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 provided, the description carries full burden for behavioral transparency. It clearly states that the skill file is unchanged and that the proposal is marked rejected with an optional reason. This covers the key behavioral aspect (non-destructive mutation) but could optionally include more detail on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the main purpose. It uses a clear Args block for parameter details. Every sentence is informative, with no fluff. This is a model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers purpose, parameters, and behavioral effect. It does not explain the return value, but the presence of an output schema makes that acceptable. It could optionally mention that the proposal is marked as rejected in the system, but overall it is complete enough for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so excellently: for 'proposal_id', it specifies the source ('from get_pending_proposals()'), and for 'reason', it explains its optional nature and purpose. This adds significant value beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reject') and clearly identifies the resource ('a pending skill improvement proposal'). It distinguishes from sibling tools like 'approve_proposal' and 'apply_proposal_tool' by explicitly stating the outcome ('without applying it').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool (rejecting a proposal) and references where to obtain the proposal ID ('from get_pending_proposals()'). While it does not explicitly list alternatives, the sibling tools provide implicit guidance. The usage is clear and direct.
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 'the file on disk is never touched — only its tracking record is deleted,' which is critical for understanding side effects. It also notes the return behavior (confirmation or note if path not found). With no annotations, this adequately 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two paragraphs plus structured Args and Returns sections. 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.
Completeness5/5Given 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 an output schema, the description covers the purpose, usage, behavioral effect, parameter details, and return values comprehensively. It addresses all necessary aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only the name and type for the path parameter. The description adds meaning by specifying it must be an 'Absolute path' and must 'match the path exactly as it was registered,' which is valuable beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Stop tracking a file so Metis no longer watches it for changes.' It specifies that it removes a single file from the tracked-files list and mentions the inverse operation, add_tracked_file, distinguishing it 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises use when a file 'is no longer relevant or was added by mistake.' It also explicitly names the inverse tool, add_tracked_file, giving context for when to use this vs. alternatives. However, it does not list other alternatives or conditions to avoid using this tool.
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 thoroughly discloses content validation requirements (six required sections in order), filename derivation from lessons.json, and return values (file path or rejection with missing sections). This gives the agent a clear behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded purpose, followed by validation details and parameter descriptions. It is comprehensive but could be slightly tighter by removing redundant phrasing. The use of bullet-like list for required sections aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, validation rules, output schema), the description covers key aspects: purpose, validation, return, and filename derivation. It does not mention prerequisites like lessons.json existence or course initialization, but the 'Step 5' context implies these. Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that slug selects the folder path, lesson_id must match an id in lessons.json (with example), and content is the full markdown body. This adds meaningful context beyond the schema names, though more detail on slug format would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it saves one drafted lesson markdown to disk as Step 5 of the course build. It specifies the action (save), resource (lesson draft), and scope (single lesson per call), distinguishing it from sibling tools like save_course_curriculum or save_course_outline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises calling it once per lesson during drafting and within the course build sequence (Step 5). It provides clear context but does not explicitly state when not to use it or list alternatives, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It clearly states it scans subdirectories, uses parent folder name as a tag, and deduplicates by title. These details cover the main behaviors (scanning, registration, deduplication) and are consistent with the tool's purpose. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) and front-loaded: first sentence states the core action, second adds scope details, third explains safety. Every sentence serves a purpose without redundancy. Ideal structure for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has low complexity (no parameters, simple scanning behavior) and an output schema exists (though not shown, the context confirms it). The description covers scanning, registration, tagging, and deduplication—sufficient for an agent to understand the tool's effect and safe usage. No obvious gaps given the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing for the description to add. Schema coverage is 100% vacuously. The description provides no parameter-related information, but none is needed. Baseline of 4 is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Scan'), the specific resource ('inputs/literature/ for new PDFs'), and the outcome ('register them in literature_metadata'). It also adds details like walking subdirectories and using parent folder name as a domain tag, making it distinct from sibling tools like 'full_scan' or 'scan_pdf_library'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that deduplication makes repeated runs safe, implying it can be run idempotently without harm. While it doesn't list alternatives or when not to use, the context of sibling tools (e.g., 'index_pdf_library') combined with the specific target folder provides reasonable guidance for selection.
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 behavior: it checks for an active session within 2 hours, resumes and returns last 5 events if found, or creates a new session and seeds context from recent memory. It also specifies the 'client' parameter options. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a short summary sentence, a behavior explanation in two bullet points, and a parameter line. Every sentence adds value, and the structure is front-loaded with the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no annotations, and an output schema (not shown), the description covers the main behavior and outcomes. It mentions returning 'last 5 events' when resuming and 'seeds context' when creating, but does not detail the output schema fields. However, since an output schema exists, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter with 0% coverage (no description), but the description adds complete meaning: it specifies the allowed values ('code', 'chat', 'cowork', 'dashboard') and its purpose ('Which Claude client is calling'). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Stage 1: Find or create a session for the current computer.' It provides a specific verb ('find or create') and resource ('session'), and distinguishes from sibling tools like list_recent_sessions by focusing on session initialization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a first step ('Stage 1') but does not explicitly state when to use this tool versus alternatives like list_recent_sessions or get_agent_context. No exclusion criteria or when-not-to-use guidance is provided.
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 explains the tool stores in semantic memory and that retrieval uses this knowledge, and lists error conditions (missing database, missing fastembed, write failure). However, it does not disclose behaviors like idempotency, updating existing concepts, or side effects, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a brief initial sentence stating purpose, then sibling comparisons, a paragraph on what semantic memory is, followed by clear Args and Returns sections. It is front-loaded with essential information and every part earns its place without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (store operation), the description is fairly complete: it explains the role of semantic memory, parameter semantics, and return type (TextContent with confirmation/error). It lacks details on handling duplicate concepts, but the error conditions and overall context suffice for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an 'Args' section explaining each parameter in detail: 'concept' with examples, 'definition' as one-to-three sentences, 'related_concepts' as comma-separated, 'source_type' with enumerated possibilities, and 'source_id' as ID. This adds significant meaning beyond the schema's mere title/type, covering all 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores a distilled knowledge node in semantic memory, using specific verb 'store' and resource 'semantic memory'. It distinguishes from sibling tools 'store_episodic_memory' (for time-stamped events) and 'add_memory_entry' (for human-curated palace note), making the purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (for timeless concepts/definitions) and when not to: 'For a time-stamped event use store_episodic_memory; for a human-curated palace note use add_memory_entry.' This provides clear guidance on tool selection among similar 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, description discloses upsert semantics (created_at preserved, definition overwritten) and return value. Adequate for a simple mutating tool; could mention idempotency or side effects but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with core purpose, efficient use of sentences, structured with Args section. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a two-param tool with output schema: covers purpose, behavior, parameters, return, and sibling relation (get_glossary). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds significant meaning beyond schema: explains term is unique key (reuse overwrites definition) and definition is the text. Schema coverage 0% so description compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific verb 'Add or update' and resource 'glossary term', clearly distinguishing from sibling 'add' tools like add_journal_entry by focusing on glossary terms and mentioning retrieval via get_glossary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for when to use (maintain consistent definitions across sessions) and mentions alternative retrieval tool (get_glossary). Lacks explicit when-not-to-use or exclusions, but guidance 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 carries the burden. It details the mechanism (appends to user-config.yaml, creates file if absent, updates existing contexts by name), the effect of the active_by_default parameter, and the return value. This is comprehensive disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy but well-structured with a clear opening, implementation details, related tools, and parameter definitions. It could be slightly more concise without losing clarity, but it remains focused and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values are adequately covered. The description explains the tool's effect on the user config and active contexts. It could mention error handling, but overall it is complete enough for a mutation tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds rich meaning to all three parameters: explains name as a key for updates, description as text, and active_by_default as controlling immediate activation. This far exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds or updates a specialist context to the user profile. It specifies the resource and action, and distinguishes itself from sibling tools like toggle_context and list_contexts by naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to inform Metis about user domains for tailored routing and search. It mentions related tools (toggle_context, list_contexts) but doesn't explicitly define when not to use it. This provides adequate but not exhaustive 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?
With no annotations provided, the description fully covers behavioral traits: it lists the patterns replaced, explains the effect of modes and the 'replace_names' option, and specifies the return format (JSON with 'anonymized' and 'replacements' keys).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro, bulleted list of replacements, and clear parameter explanations. Every sentence adds value, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only 3 parameters and no annotations, the description covers all necessary context: input, configuration, return format, and behavioral details. The presence of an output schema is acknowledged but the description already specifies the return keys.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema: it explains that 'content' is the text to anonymize, 'mode' accepts 'full' or 'preview' (enum values not in schema), and 'replace_names' is a boolean flag for heuristic name replacement. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scrubs PII from text and returns an anonymized version with a replacement map. It lists specific replacements (patient IDs, GPS, etc.) and distinguishes its function from siblings like 'diff_anonymization' by focusing on anonymization rather than comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and its modes ('full' vs 'preview'), but it does not explicitly state when to use this tool over alternatives or provide usage constraints like required permissions or privacy considerations.
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 explains the tool is non-destructive (safe while live), details the return JSON fields (backup_path, size_kb, checksum, elapsed_ms), and mentions the API used. This gives good behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose, a safety note, a bulleted argument list, and a return format summary. Every sentence adds value, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a backup tool with 3 optional parameters and a defined output format, the description covers all necessary aspects: what it does, how it works (live-safe), parameter details, and return structure. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage (no descriptions in schema), so the description must compensate fully. It does so by explaining each parameter: destination with default path, label for filename suffix, extra_destination for secondary copy. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a timestamped backup of the Metis SQLite database, using a specific verb and resource. It distinguishes from sibling tools like restore_db, list_backups, verify_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the tool uses SQLite's Online Backup API and is safe to run while the database is live, providing useful usage context. However, it does not explicitly state when to use this tool vs alternatives like restore_db or encrypt_backup.
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 exist, so description carries full burden. It explicitly states NEVER modifies original file, always writes to output_path, default naming convention, and describes the return JSON structure. This fully discloses 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: first line purpose, then immutability note, then bulleted operation list with syntax, then parameter descriptions, then return value. Every sentence adds value without wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 0% schema description coverage and no annotations, the description is fully complete. It explains all operations with syntax, parameters with defaults, and return JSON. Output schema provides additional structure but description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates completely. It explains path as absolute local path, operations as list of operation strings with examples, and output_path with default behavior. Adds full meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it applies cleaning operations to a dataset and writes a new file. It lists all supported operations and explicitly states it never modifies the original file. This effectively distinguishes it from sibling tools like 'suggest_cleaning' or 'profile_dataset'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (cleaning a dataset) but does not explicitly mention alternatives or when not to use. While it implies immutability, it does not contrast with other data manipulation tools among siblings.
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 exist, so the description carries full burden. It explains the tool reads from the database, returns newest-first results, and details the output content (run_id, agent, task summary, status, timestamp, token counts, model). No destructive behavior is implied, and the read-only nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence purpose, a paragraph on what is returned, a bulleted Args section, and a Returns section. Information is front-loaded and 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 optional parameters, no nested objects, has output schema), the description covers purpose, parameters, return format, and even the related writing tool. It is fully sufficient for correct invocation without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section thoroughly documents all three parameters: limit (default 10, newest first), since (ISO date/datetime, empty returns all), and agent_slug (filter by slug, empty returns all). This adds significant meaning beyond the type/default in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves recent agent run history from the database, specifying the resource (agent runs) and action (retrieve). It distinguishes from sibling tool log_agent_run by noting that tool writes these rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions use cases ('for the dashboard or for reviewing recent activity') and references the writing tool, but does not provide explicit guidance on when to use this tool versus other retrieval tools like search_memory or search_session_memory. No exclusions or alternatives are given, so only adequate for a 3.
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 the tool is read-only (reads registry), explains data source, and details enrichment from folder cards. It does not mention rate limits or performance, but the behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: four sentences plus an Args line. It front-loads the purpose and structure is clear with sections. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and an output schema exists, the description covers the purpose, data source, parameter semantics, and enrichment behavior. It is fully sufficient for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It does so effectively with an Args section explaining project_id supports partial matching and empty string means all active projects, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Status of your registered projects' and specifies it reads the project registry (not disk folders) and adds task completion counts. This distinguishes it clearly from filesystem-related tools like 'scan_project_folder'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the data source (registry vs. folders) and behavior for empty vs. specific project_id, giving context for when to use. However, it does not explicitly list alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the BFS algorithm and output grouping by distance. No annotations present, so burden is on description. It implies read-only operation but doesn't explicitly confirm non-destructive behavior or mention permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence serves a purpose: purpose, algorithm, use case, and parameter details. No redundant information, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, algorithm, usage context, parameter format, and output structure (grouped by distance). With output schema present, return value details are not needed. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; the description compensates fully with clear parameter definitions, including a concrete example for note_path and value ranges for depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the connected cluster around a note using BFS flood-fill. It distinguishes from sibling tools like kg_paths by focusing on community detection rather than path finding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context for when to use the tool ('useful for surfacing related concepts when working on a specific topic') but does not explicitly exclude other scenarios or mention alternatives like kg_paths.
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 discloses that approved=True advances to Step 3, but does not specify behavior when approved=False, or error handling for invalid outline_json. Lacks some behavioral details expected for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, one for usage, an example for outline_json, and bulleted Args/Returns. Well-structured and front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no schema descriptions, and an output schema that likely covers return details, the description provides all necessary context. It explains the workflow step, input format, and condition for progression.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: slug as start_course_build() return, outline_json with an example JSON array, and approved as a boolean to advance. Adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Save an approved course outline after Step 2 (Scope Plan)' with a specific verb and resource. It distinguishes from sibling tools like save_course_curriculum by placing it in a pipeline context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call ('once the user has reviewed and approved the module outline'), prerequisite (slug from start_course_build()), and condition for advancing to Step 3. Provides clear context for when this tool should be used.
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 the burden. It discloses file path pattern (outputs/reviews/...), default logging behavior, and return value. Does not cover error states or overwrite behavior, but is transparent on key behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear first sentence, followed by context, usage instruction, parameter documentation, and return description. No extraneous text, every sentence is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, parameters, usage, side effects, and return value. Output schema exists (implied by Returns section), and description complements it well, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section provides meaningful examples ('epidemiologist', 'article1-methodology') and explains the role of each parameter, including the default for log_run. This adds substantial value beyond the input schema, which only provides type and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the action 'Save an agent's output as a review file' and clearly distinguishes from sibling tools like log_agent_run and save_brainstorm_output by mentioning it is the standard way to persist work and filing results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use it at the end of any substantive agent task' providing clear when-to-use guidance. Does not explicitly mention alternatives or when not to use, but context 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?
Describes that the summary is stored to persistent memory and is searchable later. The return value is described as a dict with id and confirmation. Lacks explicit detail on overwrite behavior or limits, but adequate for the complexity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence for purpose, a paragraph for usage, structured Args section, and Returns. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects for a save operation: purpose, when to use, parameter meanings, return value. References retrieval counterpart. No gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides rich details for each parameter: required summary length, optional key_topics with examples, decisions with examples, and session_id with grouping behavior. Adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'save', the resource 'summary of current session', and the purpose 'cross-session continuity'. Distinguishes from siblings like 'save_session_event' and pairs with 'search_session_memory'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this at the end of any substantive session' and explains the benefit of cross-session continuity. Does not state when not to use, 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?
No annotations exist, so the description fully carries the burden. It discloses file detection, transcription via faster-whisper, file movement to processed/, and handling of non-audio files. However, it does not mention any side effects like overwriting or deletion, and permissions are not discussed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the primary action. Every sentence adds value, and the parameter documentation is clearly separated. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one boolean parameter, clear behavior) and the presence of an output schema, the description is complete. It covers input, processing steps, and outcome (transcript as idea, file moved). No missing critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter auto_transcribe_audio is fully explained in the description, including its default value and effect (transcribe vs list). Schema description coverage is 0%, so the description provides all necessary semantics, which is excellent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: scanning the inbox folder and auto-transcribing audio files into ideas. It specifies supported file formats, the default behavior, and the outcome (capturing transcript as an idea). This distinguishes it from sibling tools like 'capture_idea' (manual) and 'transcribe_recording' (single file).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to process audio files in inbox/auto-transcribe or list them) and the behavior of the parameter. While it doesn't explicitly list alternative tools, the context is clear for an agent to decide. Minor gap: no mention of prerequisites 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that it searches the library_fulltext table, ignores short words and stop-words, and returns a TextContent with title and highlighted snippet. It clearly explains the search behavior and output 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, structured with a summary line, sibling differentiation, and a clear Args section. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with 2 parameters and existing output schema, the description is complete. It covers query behavior, return format, and usage context, leaving no gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It thoroughly explains both parameters: query (with details on ignored words) and max_results (with default value), adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs full-text keyword search across indexed PDFs, and explicitly differentiates from siblings search_pdf_knowledge and search_library, making the tool's purpose precise and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 (keyword search) vs alternatives (semantic or metadata search) and explains the query format (space-separated, ignoring short words and stop-words). It does not include explicit when-not-to-use but covers key 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?
With no annotations, the description carries the full burden. It discloses that the tool performs substring search across indexed references (Zotero-synced + manual), matches against multiple fields, and returns newest first. It also mentions the scope (local library) and intent (avoiding internet lookups). However, it does not explicitly state that the tool is non-destructive or mention rate limits, though these are implied by context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear paragraphs: overview, differentiation, scope/order, and Args/Returns. It is front-loaded with purpose and alternatives. While not overly long, it contains more detail than strictly necessary, making it slightly less concise than ideal. Still, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 nested objects, output schema exists), the description covers all essential aspects: purpose, usage context, alternative tools, parameter details, return format, and ordering. The output schema exists, but the description also describes the return format, which is not redundant. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so with an 'Args' section explaining query as substring matching against metadata and limit as maximum results (with default 10 and ordering by newest year first). This adds significant meaning beyond the schema, though it could be slightly more precise about the substring behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches a local literature library for matching papers, specifying it searches metadata (title/authors/abstract/tags). This uses a specific verb and resource, and explicitly distinguishes from sibling tools like search_pdf_knowledge and search_fulltext.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool ('find what they already have before going to the internet') and when not to, naming alternatives: search_pdf_knowledge for meaning-based PDF search, search_fulltext for exact keyword search, and search_literature for external lookup. This provides clear 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?
With no annotations, the description fully discloses the behavior: it opens a span and returns a span_id. It does not mention side effects or destruction, which is appropriate for a tracing tool. The description adds useful context about parameter meanings and defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one summary line, a structured Args list with clear labels, and a brief return note. Every sentence adds value without redundancy. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 6 parameters and no annotations, the description covers all necessary aspects: what it does, all parameters with types and defaults, the return value, and integration with end_span. It is complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides rich semantics for all 6 parameters, including examples (e.g., 'stage_1_bootstrap' for name), enumeration of kind options, and explanations of optional fields like parent_id and tags. This far exceeds the schema's bare titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Open a new tracing span' with the verb 'open' and resource 'span', and explicitly returns the span_id for use with end_span. This distinguishes it from sibling tools like end_span, log_span, and get_spans by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters in detail and hints at usage with end_span, but does not explicitly state when to use this tool versus alternatives (e.g., log_span for logging without span structure). The guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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 local offline processing, supported formats, model size options, routing behavior, and default env var. Lacks detail on performance or error handling but is 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose, context, Args, Returns, and Examples. Every sentence adds value. No redundancy. Appropriate length for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no required params, and an output schema, the description is complete: covers all parameters, behavior, use cases, and examples. Output schema exists and description also mentions return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains each parameter in the 'Args' section: audio_path (empty for live mic), route_to (with options), record_seconds (requires dependencies), model_size (with defaults). Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Transcribe an audio file or live mic recording and optionally capture the result.' It specifies the verb (transcribe) and resource (audio file/mic recording), and hints at local offline processing which distinguishes it from potential siblings like transcribe_recording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use: for audio files or live mic capture. It provides offline privacy context. However, it does not explicitly state when not to use this tool versus alternatives like transcribe_recording, which would improve clarity.
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 behavioral traits: it treats sub-agent output with suspicion and rejects if required keys are missing or empty. Since no annotations are provided, the description carries full burden. It does not detail return values, but the system has an output schema, so that is acceptable. It could mention error formatting or success indications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with two sentences and a bulleted Args section. Every sentence provides value without redundancy. The purpose is stated upfront, and details are structured efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no nested objects) and the presence of an output schema, the description covers the validation logic, parameter meanings, and usage context comprehensively. No additional details are necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains both parameters: 'output_json' as a JSON string of the sub-agent output, and 'required_keys' as a comma-separated list with an example. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's verb ('Validate') and resource ('sub-agent output before passing to the next pipeline stage'). It distinguishes the tool's role as a quality gate in a pipeline, which differentiates it from sibling tools that perform other operations like reading, writing, or searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'before passing to the next pipeline stage'. This provides clear context. However, it does not mention when not to use it or suggest alternatives, which would have made the guidance complete.
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 the description fully discloses behaviors: it records modification time, sets watch, updates on re-add, and the effect of empty label on re-add. Could mention permissions but overall sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a brief lead, behavioral explanation, args section, and returns. Information dense but not overly long; every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 annotations, has output schema), the description covers all necessary information: purpose, usage, parameters, behavior, return value, and related tool. Fully adequate for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description adds all parameter meaning: path must be absolute and exist, label optional with default and special re-add behavior. Essential details for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool adds a single file to the tracked-files list and starts watching it. Differentiates from 'connect_project_folder' which registers a whole project, ensuring the agent understands the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (single file) and when to use an alternative (connect_project_folder for a whole project). Also states prerequisites (file must exist) and behavior on re-add.
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, description carries full burden. Discloses mandatory recording checkpoint, enforcement of at least one decision, and separate writes to episodic_memory. Could add details on idempotency or overwrites, but sufficient for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient structure: summary sentence, usage context paragraph, then bulleted args. Every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param tool with no output schema and no annotations, description covers all parameters, usage timing, sibling differentiation, and behavioral expectations. No gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description compensates with rich guidance: decisions must be 1-5 plain-English with example, summary optional but structured, key_topics with example tags, session_id optional. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a clear verb+resource: 'Commit key decisions from this session to permanent memory.' Explicitly differentiates from sibling tool save_session_summary by noting this tool enforces decisions and writes to episodic_memory, making purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly states when to use: 'call it at the end of every agent-routed session, before delivering the final result to the user.' Contrasts with save_session_summary, providing clear alternative. No guessing 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?
No annotations exist, so description fully shoulders behavioral disclosure. It explicitly states a side effect: 'The result is also written to the meeting's notes field in the database'. It also describes the return format. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise main sentence, followed by context, Args, and Returns sections. Every sentence adds value, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 needed (output is described as 'Formatted cross-reference brief'), the description covers preconditions (after saving transcript), side effects, and output. It is complete given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning by explaining that meeting_id is 'from the meetings table' and that it will extract key topics from the transcript. This provides context beyond the schema's simple 'Meeting Id' title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Find cross-references' and specifies the resource as 'a saved meeting' with explicit types: tasks, papers, projects. It distinguishes from sibling tools like transcribe_recording by indicating it is called after saving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Call this after saving a meeting transcript (via Meetings tab or transcribe_recording())'. It gives context on when to use the tool but does not explicitly state when not to use it or list alternative cross-referencing 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 provided, so description carries full burden. Discloses that it creates default config if missing—a non-obvious side effect. Lacks discussion of authorization or other constraints, but side effect is 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: main purpose, return content details, alternative tool, and side effect. Front-loaded and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and zero parameters, the description fully covers the tool's purpose, side effect, and alternative. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema (0 params, 100% coverage). Baseline 4 applies. Description adds no parameter info because none exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Return' and resource 'full Metis user configuration from user-config.yaml'. Distinguishes from sibling get_user_profile by specifying scope (full config vs lightweight profile). Lists example contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides alternative tool (get_user_profile) for lightweight profile, indicating when not to use this tool. Also notes side effect of creating config if 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 exist, so description carries full burden. It discloses the return format (JSON with specific fields) and implies no side effects. Lacks mention of potential errors or authorization, but for a simple read it is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose, one for when to use, then a structured list of return fields, and a compact usage example. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, output schema exists), the description fully covers what an agent needs: purpose, invocation timing, return structure, and parsing pattern. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100% (empty schema). Baseline score of 4 is appropriate since description adds no param info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns user identity, interests, and active model preference. It distinguishes itself from siblings by being a dedicated profile getter, and provides explicit field names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly advises to call at the start of any personalised run, which is a clear usage scenario. Also includes a code pattern showing how to parse the result, aiding proper invocation.
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 exist, so the description fully shoulders transparency. It discloses the read-only nature and details what information is returned (layer, document count, chunk count, last build date), leaving no ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences contain all necessary information. The first sentence states the purpose, and the second enriches the output details. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the presence of an output schema, the description covers all needed context: what the tool lists and what fields are reported. It is fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is trivially 100%. Per guidelines, a 0-parameter tool receives a baseline of 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact action: 'List all knowledge databases (layers) registered in Metis.' It distinguishes this tool from siblings like 'create_knowledge_database' by focusing on listing existing databases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Though no explicit 'when-to-use' or alternatives are given, the purpose is self-evident for a parameterless list tool. The description clearly states the scope (all databases, built-in and custom), making usage obvious.
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 fully discloses behavior: checks environment variable and config file, validates existence on disk, returns Path or None. No side effects are mentioned, which is appropriate for a read-only lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three well-structured paragraphs: first sentence states purpose, then explains context and lookup logic, then return type. Every sentence is necessary and no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no annotations, straightforward return), the description covers all needed aspects: purpose, usage context, configuration sources, argument absence, return type, and mentions sibling tools for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, and description explicitly states 'Takes no arguments.' With no parameters, baseline is 4, and description adds no extra but also doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool resolves the configured Obsidian vault path, specifying verb ('resolve') and resource ('vault path'). It distinguishes itself by mentioning it supports note-indexing sibling tools like kg_index_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use the tool (before note-indexing) and explains the lookup order across environment variable and config file. It does not explicitly state when not to use it, but the context is clear given the helper role.
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 all 11 pipeline stages, including bootstrapping, classification, blocking sensitive requests, cybersecurity checks, persisting the turn, and returning a routing decision. No contradictions and extensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence stating purpose, followed by a bulleted breakdown of stages and then parameter explanations. While lengthy, every sentence adds value for a complex tool; could be slightly more concise but remains effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a master pipeline, the description covers the full flow, all stages, parameter semantics, and post-call actions. An output schema exists, so the brief mention of returning a routing decision is sufficient. Complete for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It provides clear explanations for all four parameters: request (the researcher's request), session_id (auto-bootstrap if empty), client (allowed values), max_turns (default 20). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is the master entry point for the /metis pipeline, detailing its role in running an 11-stage process and returning a routing decision. It distinguishes itself by explaining its central role and how it relates to other tools (e.g., agents call save_session_event, log_agent_run, write_reflexion after).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Every /metis invocation passes through here,' clearly indicating when to use this tool—whenever running the metis pipeline. It does not provide when-not-to-use or alternatives, but given it is the master entry point, usage context 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?
Discloses that it searches a specific SQLite table (library_seeded) and returns a markdown table. Also describes error behavior for missing database/table/column or no results. Lacks explicit read-only/destructive hint, but annotations are absent so description carries full burden. A slight gap is not stating side-effect profile, but it's implied to be read-only
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Efficient and well-structured: clear opening sentence, bullet-like sibling differentiation, parameter documentation, and return description. 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for the tool's complexity: covers purpose, usage, parameters, return format, and error handling. Output schema exists (not shown) but description adequately explains returns. No missing critical info for a search tool
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: describes query as case-insensitive substring, field as column with enumerated values (all, disease, method, geography, article), and limit with default. Schema only provides types and defaults, so description adds value. Could be more precise about allowed field values but still helpful
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb-resource combination: 'Search the user's literature database.' Specifies the resource (curated/seeded literature catalogue) and the action. Explicitly distinguishes from three sibling tools (search_library, search_fulltext, search_pdf_knowledge).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and alternatives: states when to use this tool vs. search_library, search_fulltext, and search_pdf_knowledge. No when-not-to-use is needed as the guidance is 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?
No annotations provided, so the description must carry the full burden. It discloses that it inserts into the memory_entries table and optionally writes a markdown file, and describes the return value (confirmation or error). It lacks details on idempotency, concurrent access, or specific error conditions, but covers the main behavioral aspects adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise purpose statement, usage guidance, a brief internal description, then clearly labeled parameter explanations, and the return value. It is front-loaded with essential information and 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (3 required), no schema descriptions, and the presence of an output schema, the description provides comprehensive coverage. It explains all parameters, the underlying database operation, file creation, and the return type. No gaps are evident for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description's Args section provides clear, meaningful explanations for each parameter (e.g., summary: 'One-paragraph summary, stored in the DB and shown in search'). This fully compensates for the schema gap and adds value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a memory entry to the memory palace, specifies it's for human-curated notes with title, summary, and topics, and distinguishes it from store_episodic_memory and store_semantic_memory for machine logging or distilled concepts. The purpose is specific and well-differentiated 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool ('human-curated memory palace note') and provides direct alternatives: store_episodic_memory for machine logging, store_semantic_memory for concepts. This gives clear context and helps 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?
Discloses that it appends timestamped lines and keeps a single entry per day. With no annotations, it carries the full burden and does so adequately. Could be improved by noting the return format, but output schema may cover that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus args, front-loaded with purpose, no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple append/read tool with one parameter and output schema present. Covers behavior, usage, and parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds substantial meaning beyond the schema: 'text' is the line to append; leaving it empty reads the note. This compensates for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States exactly what the tool does: append to or read today's daily note. Distinguishes from sibling 'add_journal_entry' by explaining the rolling note vs. new row 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with 'add_journal_entry' to clarify when to use this tool (for daily note capture) vs. creating new journal entries. Also explains that leaving text empty reads the note, indicating a dual read/append use case.
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 description bears full burden. It describes read-only behavior, output format (list with timestamps/tags), and default sorting. Could mention pagination or absence of side effects explicitly, but current level is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise: first sentence captures core function, followed by usage context, sibling references, and clear Args/Returns sections. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (2 params, no required, output schema exists), the description covers operation, usage context, parameter details, and return format completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully explains both parameters: scope with enumerated options and defaults ('today', 'week', 'month', 'all'), limit as max count, and ordering context. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List captured ideas' and resource 'knowledge base', with explicit ordering ('newest first'). It distinguishes from siblings by naming complementary tools (capture_idea, cross_pollinate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use: 'review what you've been thinking about over a chosen time window' and identifies alternatives ('Pairs with capture_idea... cross_pollinate').
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?
Describes the internal action: stamps each with a read time to prevent resurfacing. No annotations present, so description fully compensates. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise paragraph followed by structured Args and Returns sections. Every sentence is informative with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 an output schema, the description fully covers usage, parameter semantics, and return value. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides a clear meaning for the 'ids' parameter: 'List of new_publications row IDs to mark as read; an empty list is a no-op.' This adds essential context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Mark new publications as read by their IDs' and explains the effect of clearing them from the 'new publications' queue. It distinguishes itself from the sibling 'get_new_publications' which returns the IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use IDs from 'get_new_publications' and notes that an empty list is a no-op. No explicit when-not-to-use, but context is sufficient.
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: respects off/snooze/power-user settings, frequency cap (≤1/20min, ≤3/day), records to avoid repeats, returns empty string when inappropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with core purpose and well-structured with paragraphs. Slightly verbose but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given tool complexity (frequency caps, user settings) and presence of output schema (not shown but indicated), description covers all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0%, but description adds meaning: 'comma-separated trigger tags describing what the user is doing' for the context parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns one earned, not-yet-shown feature tip (or empty string). Distinct from siblings which are mostly CRUD or search 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit trigger moments (user starts project, writes R code, etc.) and explains when not to call (if user already uses feature, frequency cap, returns empty).
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 the renaming of the current database to a timestamped backup, the overwrite action, loss of changes, and the need to restart the dashboard. It also notes the return format, providing complete 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear purpose sentence, step-by-step explanation, important warnings, and parameter descriptions. It is concise with no unnecessary information, every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a restore operation with a safety rename, the description covers the process, the confirm parameter, the implications of overwriting, and the need for dashboard restart. An output schema exists but the description already mentions the return format, making it complete enough for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage). The description compensates by explaining that backup_path is a full path to a .sqlite file and confirm must be the string 'YES'. This adds essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Restore the Metis database from a backup' using a specific verb and resource. It explains the renaming behavior and distinguishes the tool from siblings like backup_db and verify_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that the operation overwrites the live database and requires a dashboard restart, implying when to use. However, it does not explicitly state when not to use or mention alternatives, leaving room for clearer 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 are provided, so the description carries the full burden. It describes the vector similarity approach (768-dim nomic-embed), indicates the tool is read-only (RAG retrieval), and specifies the return format. However, it does not explicitly state non-destructive behavior, potential latency, or preconditions like indexing status. Slight gap prevents a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, sibling differentiators, technical detail, and then Args/Returns sections. Every sentence adds value, and the key information is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 3 parameters and an output schema, the description covers all relevant aspects: query semantics, database selection, result count, and return format including fields (title, similarity score, layer, etc.). It also handles edge cases like empty index or no matches. Complete and informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so thoroughly: query is described as a 'natural language question or keyword phrase,' databases as 'list of database slugs' with examples, and top_k with default value. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs semantic/vector search across knowledge database layers on PDF chunks. It explicitly distinguishes from siblings: search_fulltext for exact keyword, search_library for reference metadata, and semantic_search for personal notes. This meets the 5 standard for specific verb+resource and 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 Guidelines5/5Does 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: 'for exact keyword matches use search_fulltext; for reference metadata use search_library; for your own notes/memory use semantic_search.' It also explains that you can search a single layer or combine layers, with examples. This fully meets the criteria for explicit when/when-not/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?
Discloses that the category label is assigned or changed, whitespace is trimmed, and returns a confirmation message. Lacks mention of error conditions or permissions, but overall informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with separate paragraphs for purpose, usage, args, and returns. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple two-parameter tool with output schema; covers purpose, parameters, return, and usage context adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds full semantic context for both parameters: project_id and category, with examples and trimming behavior. Compensates for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'assign or change' and the resource 'project's category'. Differentiates from sibling tools like get_project_categories and create_project by specifying its unique action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call get_project_categories first to reuse existing labels, preventing duplicates. Provides clear when-to-use and when-not-to 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, so the description carries full burden. It describes logging a time-stamped event and indexing for vector search, mentions possible errors (database missing, fastembed not installed), and return format. However, it does not discuss write permissions, idempotency, or concurrency. Still, it clearly communicates the non-trivial side effect of indexing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise first sentence stating purpose, followed by usage guidance, then Args and Returns sections. No redundant or vague statements. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, 1 required, and no output schema provided, the description covers purpose, usage, parameter details, and return values. It also references sibling tools and error scenarios, making it complete for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It includes an 'Args' section that explains each parameter: content (required), event_type (with enumerated values), session_id (optional), metadata (JSON string with extra fields). This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Store an event in episodic memory and index it for vector search.' It uses a specific verb ('store') and resource ('episodic memory'), and differentiates from siblings by naming store_semantic_memory and add_memory_entry 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use this tool vs alternatives: 'For a distilled, timeless concept/definition use store_semantic_memory; for a human-curated palace note use add_memory_entry.' Also defines episodic memory as a chronological log.
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: empty arguments leave unchanged, marking recurring task done auto-creates next occurrence, and output format (confirmation or not-found). Without annotations, this covers the main behavioral traits, though it doesn't address concurrency or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and efficient: opening purpose sentence, usage paragraph, Args list with clear formatting, and Returns section. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a 7-parameter tool with no schema descriptions. Includes returns information, references sibling tools for ID lookup and deletion, and explains partial updates. With an output schema present, the description's return summary is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: task_id is required and sourced from get_tasks, status has explicit allowed values, due_date has format, recurrence explains special value 'none' to clear. This adds critical meaning beyond the schema's defaults and empty strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing task and lists all modifiable fields (status, title, owner, notes, due date, recurrence). It positions itself as the companion to create_task and get_tasks, differentiating from delete_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (mark done/blocked, reschedule, reassign, edit details), how partial updates work (only passed fields changed), and side effects (recurring task completion creates next occurrence). Provides alternative tool names for finding task_id (get_tasks) and removing tasks (delete_task).
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 that it is a no-op (returns '') if the intro was already given or tips are off. 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with output schema, description covers purpose, usage, and behavior completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline score of 4 applies as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns a tiny first-run orientation with 3-5 highest capabilities. Distinguishes from sibling tool `next_discovery_tip`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use once for a brand-new user or when asked 'what can you do?', then rely on `next_discovery_tip`. Also states it's a no-op if already given or tips off.
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 describes the retrieval pipeline, fusion method (RRF with k=60), deduplication, and return format, making the tool's behavior transparent without 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (overview, differentiation, pipeline, args, returns). It's detailed but not overly verbose; every sentence adds value, though slightly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, no output schema shown but described), the description covers purpose, usage, parameters, return format, and error messages fully, making it contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description's 'Args:' section thoroughly explains each parameter: query (natural language), layers (comma-separated options), top_k (default 5), providing essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches across memory layers using vector similarity + keyword RRF fusion, and explicitly contrasts with other tools like search_pdf_knowledge and search_library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use and when-not-to-use guidance, name-dropping alternatives (search_pdf_knowledge, search_library) and explaining the retrieval pipeline, which helps the agent decide effectively.
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 the destructive nature ('cannot be undone'), the action (removes row entirely), and the return value (confirmation or note of non-existence).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Seven sentences, front-loaded with core purpose, no filler. Well-structured: purpose, context, alternatives, prerequisite, return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and an output schema, the description covers everything needed: what it does, when to use, how to find the ID, and what to expect in return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains the single parameter task_id: 'ID of the task to delete (as shown by get_tasks). Required.' This adds crucial context on how to obtain the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Permanently delete a task from the database.', specifying the verb and resource. Distinguishes itself from create_task and update_task by describing its destructive complement role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (for tasks created in error or no longer relevant) and when to use update_task instead (to mark work finished). Also provides prerequisite: find task_id with get_tasks.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/SVerITG/Metis_PH'
If you have feedback or need assistance with the MCP directory API, please join our Discord server