Metis

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

With no annotations, the description fully discloses behavior: upsert semantics (keeps created_at, overwrites definition) and return type (confirmation message). This is comprehensive.

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

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

The description is concise and well-structured: a clear summary followed by detailed args and returns. Each sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 string params) and the presence of an output schema, the description covers all needed context: upsert behavior, use case, and retrieval sibling. It is complete.

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

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

The description adds meaning beyond the schema by explaining that 'term' is the unique key and 'definition' is the stored text. With 0% schema coverage, this is essential.

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

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

The description clearly states it adds or updates a glossary term, specifying the action and resource. It distinguishes from the retrieval sibling 'get_glossary' by mentioning retrieval separately.

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

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

The description explains when to use it (maintaining a personal glossary for consistent definitions) and explicitly describes the upsert behavior. It also directs to 'get_glossary' for retrieval, providing clear guidance on alternatives.

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

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

The description notes auto-extraction of mood and energy, but lacks details on side effects, idempotency, required permissions, or what the return value contains (output schema exists but 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.

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

The description is extremely concise with no wasted words, efficiently conveying the tool's purpose and parameters in two lines plus an Args list.

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

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

While the description covers the core function, it omits behavioral details like constraints on content length, persistence behavior, or post-storage results. Given the tool's simplicity, it is minimally adequate but has clear gaps.

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

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

With 0% schema coverage, the description provides succinct but clear explanations for both parameters (content text, optional image path), adding value beyond the schema names.

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

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

The description clearly states the tool stores a journal entry with auto-extracted mood and energy, distinguishing it from sibling add_* tools like add_memory_entry or add_glossary_term.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., add_memory_entry or other logging tools). There is no mention of prerequisites or constraints.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It explains that the tool inserts into a database table and optionally writes a markdown file, and describes the return value. It lacks details on permissions or side effects, but is generally transparent.

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

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

The description is well-structured with sections (purpose, usage, args, returns) and is front-loaded. It is slightly long but every sentence is informative, earning its place.

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

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

Given the tool's complexity (6 parameters, 3 required) and the presence of an output schema, the description fully covers input semantics, behavior (database insert and optional file write), and return format. No gaps remain.

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

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

With 0% schema description coverage, the description adds comprehensive meaning for each parameter, including allowed values for 'entry_type', comma-separated format for 'topics', and the role of 'detail' in creating a markdown file. This goes well beyond the basic schema.

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

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

The description clearly states 'Add a new memory entry to the memory palace' with a specific verb and resource, and explicitly distinguishes itself from sibling tools 'store_episodic_memory' and 'store_semantic_memory'.

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

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

The description explicitly guides when to use this tool ('human-curated memory palace note') and when to use alternatives ('For machine/agent event logging use store_episodic_memory; for a distilled concept/definition use store_semantic_memory').

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

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

With no annotations, the description carries the full burden. It discloses that the reminder appears as a chip on the Work calendar, explains that a repeating plan is stored as one row and expanded on render, notes that recurring multi-day events are unsupported and should be flagged rather than silently resolved, and describes the return confirmation. These details give the agent a complete behavioral picture.

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

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

The description is well-structured with a clear front-loaded purpose statement, then an Args section, and a Returns section. Every sentence adds value, and despite its length, the information is necessary given the 7 parameters and 0% schema coverage. There is no redundant or filler content.

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

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

Given the complexity of the tool (7 parameters, recurring events, multi-day spans) and the absence of annotations, the description provides everything an agent needs: when to use, how to format each parameter, behavioral caveats, and what to expect on return. The existence of an output schema does not make the Returns note superfluous because the description confirms the confirmation content.

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

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

Schema description coverage is 0%, so the description must fully document all parameters. It does so thoroughly: it explains the purpose and format of each of the seven parameters, including examples for date phrases, the mutually exclusive interpretations of `until` depending on `repeat`, allowed values for `repeat`, default behavior for `duration_days`, and the optional nature of `project_id`.

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

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

The description states a specific verb and resource: 'Put a reminder on the researcher's dashboard calendar.' It clearly distinguishes from tasks or notes by calling it a reminder and describing its appearance as a chip on the Work calendar. However, it does not explicitly name a sibling alternative or contrast itself with other scheduling tools in the sibling list.

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

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

It gives clear usage context: 'Use this whenever they ask to be reminded of something, or whenever you agree to come back to something later.' This tells the agent when to invoke the tool, but it does not state when not to use it or offer explicit alternatives for similar needs.

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

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

With no annotations, the description fully discloses behavioral traits: it modifies user-config.yaml, creates the file with defaults if absent, updates instead of duplicating on name match, and explains the active_by_default parameter's effect on activation state. The return value type is also specified.

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

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

The description is efficiently structured: opening sentence for purpose, explanatory paragraphs, a 'Related tools' line, then 'Args:' and 'Returns:' sections. Every sentence provides value, with no redundant or extraneous content.

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

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

Given the tool has 3 parameters, no annotations, and an output schema, the description covers all necessary aspects: purpose, behavioral details, parameter semantics, and return value. It enables an agent to correctly select and invoke the tool without additional context.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains each parameter: name as short label and dedup key, description as one/two sentences, and active_by_default with behavior (immediate activation vs storage/inactivation). This adds critical meaning beyond the schema's title and default.

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

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

The description clearly states the action (add or update) and the resource (specialist context). It distinguishes between adding and updating, and the context of routing/search tailoring provides specificity. The sibling tools list includes toggle_context and list_contexts, which helps differentiate.

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

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

The description explains when to use the tool (to add or update specialist contexts for tailoring) and mentions related tools (toggle_context, list_contexts). However, it does not explicitly state when not to use it or provide alternatives beyond listing related tools, leaving room for slight ambiguity.

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

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

No annotations, but description covers key behaviors: records modification time, sets watch, re-add updates, file must exist, returns confirmation or error. No hidden side effects mentioned.

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

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

Well-structured with summary, details, Args, Returns. Slightly verbose but adds necessary context. Efficient overall.

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

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

Given output schema exists, description still clarifies return values. Covers prerequisites, re-add logic, alternative tool. Fully adequate for a simple file-tracking tool.

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

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

Schema coverage 0%, so description adds full meaning: path must be absolute and exist, label is optional with default empty and on re-add empty label leaves old unchanged. Outperforms basic schema.

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

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

Clearly states 'Add a single file to the tracked-files list and start watching it.' Identifies specific verb, resource, and action. Distinguishes from sibling 'connect_project_folder' for bulk registration.

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

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

Explicitly says when to use (register one file) and when not ('To register a whole project at once, use connect_project_folder'). Also explains re-adding behavior.

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

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

No annotations are provided, so the description must fully disclose behavior. It states it adds a topic but does not mention whether duplicates are allowed (despite hinting at 'unique' in param doc), what side effects occur (e.g., triggers notifications), or what happens if the topic already exists. This lack of behavioral detail is a significant gap.

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

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

The description is very short and front-loaded with the purpose, but it uses Python docstring style with 'Args:' which is unnecessary for JSON. It is concise but could be more efficiently structured without the docstring formatting, potentially adding a return description or behavior note.

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

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

Given the tool has an output schema (not shown) and low complexity (2 params, no enums), the description is incomplete. It does not explain the return value, error conditions (e.g., duplicate topic), or the lifecycle of added topics. The tool's purpose is clear but operational details are missing for a complete understanding.

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

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

Schema description coverage is 0%, so the description must add value. It only repeats parameter names with minimal context ('topic: Topic name (unique)', 'description: Optional description...'). The schema already contains required/default info; the description does not explain formats, constraints, or usage examples, adding little beyond the schema.

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

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

The description clearly states the tool's purpose: 'Add a topic to track for new publications.' It uses a specific verb ('Add') and resource ('topic'), and distinguishes from similar sibling tools like add_glossary_term or add_memory_entry by specifying the context of tracking new publications.

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

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

No guidance on when to use this tool versus alternatives (e.g., search or list tools). There is no mention of prerequisites, usage context, or when not to use it. The description is purely operational without contextual decision support.

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

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

No annotations provided, but the description clearly states it reads 'reflexion_log' entries (non-destructive) and returns aggregated themes. It does not contradict any annotations. Slight lack of mention of potential side effects, but none expected.

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

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

The description is relatively concise (3 sentences) and front-loaded with the core purpose. It could be slightly tighter but is clearly structured.

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

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

Given an output schema exists, the description covers the input parameters, data source, time window, and output categories sufficiently. It does not need to detail return values.

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

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

Schema description coverage is 0%, but the description adds meaning: 'days' is time window (default 14 days), 'agent_slug' scopes to one agent or all. This compensates for the missing schema descriptions.

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

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

The description uses a specific verb ('Theme') and resource ('recent reflexions per agent') with clear scope (Phase 9b). It distinguishes from siblings like 'consolidate_reflexions' by focusing on aggregation and thematic grouping.

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

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

The description implies when to use (to get top themes from recent reflexion logs) but does not explicitly mention when not to use or suggest alternatives among the many sibling tools.

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

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

With no annotations, the description fully carries the burden. It discloses the regex-based nature, no execution, no data access, and no LLM exposure. It does not cover error handling or side effects, but the output schema covers return values.

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

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

The description is extremely concise: two short paragraphs plus an Args section. Every sentence adds value, with no redundancy or filler.

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

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

For a simple one-parameter tool with an output schema, the description is complete. It explains the extraction method, limitations, and safety aspects, leaving no obvious gaps for the agent.

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

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

The single parameter 'path' has 0% schema description coverage, but the description adds crucial context: 'Absolute path to the script file (.R, .Rmd, .qmd, or .py).' This specifies format and absolute path requirement, adding significant value beyond the schema.

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

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

The description clearly states it parses R or Python scripts and extracts structured metadata. The verb 'parse' and resource 'script' are explicit, and it distinguishes itself from sibling tools by focusing on static analysis without execution.

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

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

It explains that parsing is regex-based with no execution, no AST, no data access, and code is not sent to an LLM. This provides clear guidance on when to use the tool safely, though it doesn't explicitly list alternatives or when not to use it.

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

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

With no annotations provided, the description fully bears the burden. It details the replacement behavior (list of PII types), modes ('full' vs 'preview'), and the optional name replacement heuristic. It also describes the output JSON structure, leaving no ambiguity about 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.

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

The description is concise yet comprehensive, using bullet points for replacements and clear sections for args. Every sentence adds value without redundancy.

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

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

Given the tool has 3 parameters, an output schema, and no nested objects, the description covers all necessary aspects: what it does, how to use it (args), and what to expect (output JSON with 'anonymized' and 'replacements'). It is fully complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 0% (no descriptions in schema). The description compensates by explaining all three parameters: content (text to anonymize), mode (full/preview), and replace_names (heuristic for CAPITALIZED tokens). It also explains the output format, adding significant value.

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

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

The description clearly states 'Scrub PII from text and return anonymized version + replacement map.' It lists specific PII types and their replacements, distinguishing it from sibling tools like redact_data_file or diff_anonymization.

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

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

The description explains the tool's purpose and parameters (mode, replace_names) but does not explicitly state when to use this tool versus alternatives like redact_data_file or diff_anonymization. However, the context is clear enough for an agent to infer usage.

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

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

With no annotations, the description carries full burden. It discloses the write-to-disk action, backup creation, and database update. However, it fails to mention whether the operation is reversible (backup implies some reversibility but not explicitly), required permissions, or behavior on invalid proposal_id. Some transparency, but gaps remain.

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

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

The description is three sentences plus an Args line, front-loaded with the primary action. Every sentence adds value: what it does, backup detail, database update, parameter meaning. No unnecessary words.

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

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

Given the existence of an output schema (not shown), the description covers the main effects: write, backup, status update. It does not explain error handling or state prerequisites, but for a single-parameter tool with clear purpose, it is largely sufficient. Minor completeness gaps leave room for improvement.

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

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

The schema provides 0% description coverage, so the description must compensate. It explains the parameter 'proposal_id' as 'the id from skill_improvement_proposals', giving context beyond the schema's bare type and title. This is helpful for agent understanding, though additional detail on validity constraints would improve it further.

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

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

The description clearly states the verb 'Apply' and the resource 'self-improvement proposal', with specific actions: writes change to disk, backs up previous content, updates proposal row. This distinguishes it from sibling tools like 'propose_skill_improvement' (creation) and 'approve_proposal' (state change) by focusing on execution.

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

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

The description implies the tool is used when a proposal is ready to be applied, but it does not explicitly state when to use it versus alternatives like 'approve_proposal' or 'reject_proposal'. No prerequisites or conditions for use are mentioned, leaving the agent to infer context.

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

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

Discloses key behaviors: writes to skill.md, marks as approved, creates backup. No annotations provided, so description carries full burden. Could mention failure modes or return value, but output schema exists to 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.

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

Four sentences plus an Args section. Every sentence provides necessary information without redundancy. Front-loaded with the core action.

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

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

Given the complexity (single required parameter, output schema exists), the description covers the essential action and side effects. Could mention that the proposal must be pending, but this is implied by the purpose.

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

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

Description adds meaning to the sole parameter 'proposal_id' by specifying it is 'The numeric ID from get_pending_proposals()', guiding the agent on how to obtain the correct value. Schema only says integer, so this adds significant value despite 0% schema description coverage.

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

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

Clearly states the verb 'approve' and the resource 'pending skill improvement proposal'. Distinguishes from siblings like 'reject_proposal' and 'propose_skill_improvement' by specifying that it applies the proposal by writing to skill.md and marking as approved.

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

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

Description provides clear context that this tool is for approving proposals from get_pending_proposals() and mentions the backup creation. It doesn't explicitly say when to use vs alternatives, but the purpose is self-evident given the sibling tool names.

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

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

With no annotations, the description carries the full burden. It discloses the core behavior: sets status='archived', keeps in DB, affects default view but not search. It does not mention permissions, reversibility, or side effects, but for a simple archive operation the transparency 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.

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

Three concise sentences plus an Args line. The first sentence states the core purpose, the second provides the SQL detail, and the third explains the effect. No wasted words; information is well-structured and front-loaded.

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

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

Given low complexity (one parameter, simple action) and the presence of an output schema, the description covers the key aspects: what happens to the item, its visibility, and the parameter meaning. Minor gaps like reversibility or permissions are not critical for this tool.

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

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

The schema has 0% description coverage, so the description must explain the parameter. It does so by stating that relative_path is the primary key in the library_seeded table, adding context beyond the parameter name. This is sufficient, though a format example could improve it.

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

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

The description clearly states the verb 'Archive' and the resource 'library item,' explaining that it marks an item as no longer active but keeps it in the database. It distinguishes this from deletion (e.g., remove_library_item) by noting the item remains searchable and cross-pollinated.

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

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

The description explains the effect (disappears from default view, stays searchable) but does not explicitly state when to use this tool versus alternatives like remove_library_item or archive_project. The usage context is implied rather than directly guided.

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

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

With no annotations, the description carries the full burden. It transparently describes that the project's status is set to 'archived', data is kept, and visibility changes. It does not mention side effects or reversibility, but the 'unarchive_project' sibling partially addresses that.

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

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

The description is extremely concise: two sentences plus a parameter listing. All information is relevant and front-loaded. No unnecessary words.

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

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

Given the single parameter and existence of an output schema, the description covers the essential aspects: what the tool does, the effect on data availability, and the parameter. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

The input schema has 0% description coverage, but the description includes an 'Args' section that explains the required 'project_id' parameter. This adds meaning beyond the schema, though it could provide more detail (e.g., format or example).

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

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

The description clearly states the tool's action: 'Archive a project — marks it inactive but keeps all data.' It uses a specific verb ('archive') and resource ('project'), and distinguishes itself from siblings like 'remove_project' and 'unarchive_project' by clarifying that data is preserved and the project remains available for context and search.

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

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

The description explains the effect ('disappears from active view but remains available for brainstorm context and search'), implying when to use it. However, it does not explicitly state when not to use it or compare with alternatives like 'remove_project'. The guidance is clear but could be more explicit.

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

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

With no annotations, description carries full burden. It discloses that the tool searches a pre-built index and returns synthesized citations, implying non-destructive read-only behavior. However, it doesn't explicitly state no side effects 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.

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

Concise and front-loaded: one sentence for purpose, minimal parameter list. No filler, but could be slightly more structured.

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

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

Given sibling tools and presence of output schema, description covers primary use case, dependency on index, and scope variants. Lacks details on return format but output schema handles that.

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

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

Schema description coverage is 0%, but the description's 'Args' section explains each parameter: question, top_k (default 5), and scope with concrete options (default, ph_library). Adds significant value beyond bare schema.

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

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

Description clearly states the tool answers a question using the user's indexed PDF library via PaperQA2, returning a synthesized answer with citations. It distinguishes from sibling tools like search_library by focusing on synthesis rather than raw retrieval.

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

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

Provides guidance on prerequisite (build index first with index_library_pdfs) and explains scope options. Could be stronger by explicitly listing when not to use, but gives adequate context.

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

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

Mentions 8000 char limit per source and returns assembled string with source labels, but does not explain what 'recent content' means, behavior when sources are empty, or default behavior when date_filters is null. With no annotations, more detail would improve transparency.

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

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

Concise and well-structured: one sentence for purpose, then clear details on char limit and output, then arg descriptions in docstring style. No unnecessary words.

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

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

Given two params, no annotations, and an output schema, the description covers essential aspects: sources, char limit, date filters example. However, it lacks definition of 'recent' and default filtering behavior, which slightly reduces completeness.

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

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

Schema coverage is 0%, so description compensates well by explaining that sources is a list from a set of allowed values (library, meetings, news, ideas, journal) and that date_filters is an optional dict with source-specific date filters, including an example. Adds significant meaning beyond the schema structure.

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

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

Clearly states the verb 'assemble' and the resource 'context from multiple sources for brainstorming'. Distinguishes from sibling tools like brainstorm_turn or get_brainstorm_session by focusing on gathering context from specific sources.

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

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

Implies usage for brainstorming context assembly but does not explicitly state when to use versus alternatives like load_project_context or get_agent_context. No 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.

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

With zero annotations the description carries the full burden, and it does meaningful work: it discloses that the tool writes DOIs into `pdf_index_state`, that local matching is free, that Crossref is gated behind `resolve_online` and costs one request per unresolved document, and that metadata only is fetched. It stops short of stating idempotency on re-runs, failure handling for unmatched documents, or any auth/rate-limit ceiling on the Crossref path.

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

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

The concrete mechanism sentence is well front-loaded in the second paragraph, but the description opens with a rhetorical question and spends a full paragraph on philosophy ('a containment problem rather than a truth problem') that an agent does not need in order to invoke the tool. The Args/Returns blocks are efficient, but the rationale prose should be trimmed.

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

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

An output schema exists and the description still summarizes the return shape (per-layer provenance counts and what changed), parameters are fully covered, and external-call costs are disclosed — enough for correct invocation. Missing is any hint about prerequisites (Crossref credentials, enabled layers) or how this relates to adjacent stats/pending-index tools.

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

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

Schema coverage is 0%, so the description must compensate and largely does: `layer` gets a concrete example slug plus the omit-for-all semantics, `resolve_online` gets both behavior and cost, and `limit` gets its default of 400. It does not say how invalid layer slugs behave or how limit interacts with multi-pass runs, so it is strong rather than exhaustive.

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

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

The description names a concrete mechanism ('Sweeps `pdf_index_state` and records a DOI for every indexed document') rather than restating the name, so the action and resource are unmistakable. It also positions itself relative to answer-time verification ('verify at ingest, trust at read'), which implicitly separates it from verify_claim/verify_text_citations, but it never names a sibling outright.

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

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

Usage is implied through the cost rationale ('paid once per document instead of once per claim') and through the local-first/Crossref-later rule, which tells the agent how to run it cheaply. There is no explicit when-to-use trigger, no when-not-to-use, and no named alternative such as verify_doi, mine_references, or index_pending_layers.

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

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

With no annotations, the description carries full burden. It discloses the use of SQLite's Online Backup API, safety for live databases, and return fields (backup_path, size_kb, checksum, elapsed_ms). This is more than basic transparency.

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

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

The description is concise, front-loaded with purpose, followed by a safety note and bulleted argument list. The return value description is included. Slightly verbose due to redundant argument list with schema, but overall efficient.

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

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

For a tool with 3 optional parameters and no required ones, the description fully covers purpose, safe usage, parameter details, and return format. No obvious gaps.

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

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

Schema description coverage is 0%, but the description provides clear explanations for all three parameters: destination (default path), label (filename appendix), and extra_destination (secondary copy). 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.

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

The description specifies the action (create), resource (timestamped backup), and context (Metis SQLite database). It clearly distinguishes from sibling tools like restore_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.

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

The description states it is safe to run while the database is live, providing good context. However, it does not explicitly state when not to use or mention alternatives like encrypt_backup.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool fetches relevant ideas, notes, questions, and library notes, lists five steering modes with their meanings, explains session continuation via session_uuid, and describes the return format including session_uuid, turn_number, context, steering_prompts, and instructions. This is comprehensive.

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

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

The description is well-structured with a summary sentence, usage instruction, enumerated steering modes, and a parameter list. Every sentence adds value, though the parameter list could be more concise. Overall, it's appropriately sized for a complex tool.

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

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

Given the tool complexity (iterative brainstorming with multiple steering modes) and the presence of an output schema (mentioned in description), the description is complete. It covers purpose, when to use, all parameters with semantics, steering modes, session management, and return value fields. No significant gaps.

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

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

Schema description coverage is 0%, but the description fully explains each parameter: topic (the brainstorm topic), steering (with explicit list of allowed modes), session_uuid (continuation vs new session), and turn_notes (optional notes). This adds complete semantic meaning beyond the schema's minimal type definitions.

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

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

The description clearly states 'Run one turn of a brainstorm session, returning relevant context.' It specifies the verb and resource, and distinguishes from sibling tools like get_brainstorm_session and save_brainstorm_output by focusing on iterative turns with steering modes.

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

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

Explicit guidance: 'Call this at the start of a brainstorm and after each steering action.' This clearly indicates when to use. While it doesn't explicitly list when not to use, the context makes it clear this is for iterative brainstorming, and siblings cover other phases.

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

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

No annotations provided, so description must cover behavior. It discloses use of local embeddings and no API key, and explains the force_rebuild parameter. However, it omits whether the tool creates databases, the scope of files indexed, potential resource usage, or side effects on existing data.

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

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

Concise, well-structured. Begins with core purpose, then model details, layer examples, and a clear Args block. No filler sentences.

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

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

Given the output schema exists, return values are not needed. However, important context is missing: how PDFs are associated with a database, whether the database must exist beforehand, and any time/resource implications. Adequate but with gaps.

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

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

Schema coverage 0% but description compensates well: explains 'database' as a slug with defaults and examples, and 'force_rebuild' as re-indexing already indexed files. 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.

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

Description clearly states it indexes a knowledge database layer from PDFs, using a local embedding model. It provides examples of database slugs and links to create_knowledge_database(), but does not explicitly differentiate from sibling tools like index_library_pdfs or index_pdf_library.

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

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

No explicit when-to-use or when-not-to-use guidance. The mention of local model implies offline use, but there is no comparison to alternatives or prerequisites for custom databases.

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

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

No annotations, so description bears full burden. It discloses auto-tag extraction, domain/project linking, and cross-pollination behavior. Could mention if other tables are modified, but overall adequate.

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

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

Concise, front-loaded with main action, and uses 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.

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

With output schema present, return values need not be described. Covers core functionality, side effects, and parameter details. Could mention content length constraints but not critical.

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

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

Schema coverage is 0%, but description adds meaningful context for all 4 parameters: content as idea text, source with default, image_path optional, and auto_cross_pollinate with behavior explanation. Fully compensates for schema gaps.

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

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

Description clearly states 'Store an idea in the SQLite ideas table' with specific verb and resource. Distinguishes from siblings like add_memory_entry and capture_observation by mentioning auto-tagging and cross-pollination.

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

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

Implies usage for capturing ideas with automatic connections, but no explicit when-not-to-use or alternatives. The cross-pollination feature is highlighted, but no guidance on when to disable it.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions recall in future sessions, implying persistence, but does not address side effects, mutability, authorization needs, or error behavior. This is a significant gap given the absence of annotations.

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

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

The description is well-structured with a clear purpose, followed by parameter details. It is concise without fluff, though the parameter list is somewhat lengthy. Front-loading the purpose aids quick understanding.

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

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

Given the output schema exists, return values are covered. The description explains what the tool does and its parameters adequately. However, it lacks details on error handling, rate limits, or required permissions, leaving some context gaps for an agent.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter's purpose, expected format (e.g., content: 1–3 sentences), and default behavior (e.g., concepts auto-extracted). This adds meaning beyond the raw schema.

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

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

The description clearly states the tool records typed observations during an agent run, with specific observation types (discovery, decision, etc.) and the purpose of enabling recall in future sessions. This distinguishes it from sibling tools like add_memory_entry 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.

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

It advises using the tool throughout a run to capture learning, but does not explicitly state when not to use it or suggest alternatives like add_memory_entry or add_journal_entry. The guidance is implied but lacks explicit exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It discloses what the tool returns (safety status, classification, warnings, next steps) and prescribes a conditional next action based on the result. It does not explicitly state whether the tool is read-only or whether it has side effects, but the 'check' framing and subsequent logging via a separate tool strongly imply it is non-mutating. A 4 reflects strong but not exhaustive disclosure.

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

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

The description is front-loaded with the imperative 'call FIRST' and structured logically (purpose, when to call, what to do based on result, return values, args). Slightly verbose but every sentence adds useful information, and there is no filler.

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

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

Given the tool's safety-critical role, no annotations, and an existing output schema, the description provides everything an agent needs: precise triggering conditions, conditional next steps, return summary, and parameter meanings. No critical gaps remain.

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

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

Schema coverage is 0% (no parameter descriptions), so the description must compensate. It does: 'content: Text content to scan' and 'file_path: Optional file path for context-based classification' add meaning beyond the bare titles. It could specify expected file path format, but the core semantics are clear.

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

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

The description states a specific verb ('check') and resource ('pasted or shared data for personal identifiers'), and explicitly distinguishes this tool from later steps in the workflow (anonymize_text, log_consent_event). An agent can immediately tell what the tool does and why it exists.

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

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

It gives explicit when-to-use guidance ('call FIRST, before analysing', 'whenever the researcher pastes or shares rows about individual people'), when-not-to-analyse guidance ('if the result is not PUBLIC, do not analyse the raw rows'), and names alternatives ('mask them with anonymize_text, log the event with log_consent_event'). This is a complete usage recipe.

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

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

With no annotations, the description carries the behavioral burden and does so well: it explains local computation, optional PubMed/OpenAlex querying, metadata-only transmission, and that returned search results are attributed rather than quoted. It also warns not to present search results as equivalent to corpus evidence.

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

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

The definition is front-loaded with the core question and then structured into behavior, args, and returns. It is generally efficient, though the staleness illustration is slightly verbose and could be tightened.

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

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

Given the absence of annotations, the presence of an output schema, and only three parameters, the description is complete enough to call the tool correctly. It covers purpose, optional online behavior, parameter meanings, privacy constraints, and citation caveats.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: `question` is illustrated with an example, `search_online` explains exactly what remote sources are queried, and `limit` is described as a per-source maximum with its default.

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

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

The description states a specific verb and resource: checking how old the topic corpus is and optionally finding newer publications. It distinguishes the local recency check from the online search and from downstream citation verification via `verify_doi`.

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

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

It gives clear usage context: recency is computed locally first, and `search_online=True` is an optional escalation that should be asked about first. It also names `verify_doi` as the required follow-up before citing online results, though it does not explicitly list 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.

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

With no annotations, the description carries the full burden and does it well: it discloses the feedparser silent-failure behavior, that requests are sequential and deliberately spaced to avoid false 403s (i.e., the call is slow and rate-limit-aware), and that per-feed results are either working status plus recency or an HTTP status to fix. These are exactly the traits an agent needs to interpret results and set expectations.

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

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

The operational content is front-loaded in the first sentence and the remaining paragraphs are structured (why / behavior / args / returns). The anecdotal 2026-08-19 measurement (14 of 33 feeds dead) is persuasive but longer than needed — it earns partial place as motivation but could be one clause.

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

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

A one-parameter diagnostic tool with an output schema, yet the description still covers motivation, rate-limit behavior, parameter meanings, and the shape of results. Nothing an agent needs to invoke or interpret it correctly is missing.

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

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

Schema coverage is 0% and the schema exposes no enum, so the description must define `kind` — and it does, mapping 'news' to the News surface, 'paper' to journal ToCs/preprints in the Library, and 'all' to both, plus the default. 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.

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

The first line states a specific verb and resource — check every feed and report which are working — and the body contrasts it with `scan_news_feeds`, which reports item counts without distinguishing dead feeds. An agent can tell this is a diagnostic tool, not a content-fetch tool, without opening the schema.

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

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

The 'Why this exists' section makes the selection condition clear in practice: when a scan reports 0 items and you need to know whether feeds are dead or merely quiet, use this instead of `scan_news_feeds`. It stops short of an explicit directive ('call this before/after scanning when X'), so it is strong context rather than a full when-to-use rule.

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

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

No annotations exist, yet the description carries the full burden: it declares the tool does no inference, lists exactly what it validates (role coverage, column existence, extraneous mappings), explains the historical failure that motivated the design, and describes the ready/not-ready return plus caveat reprinting. The non-guessing behavior is precisely the trait an agent most needs to know.

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

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

Purpose and the agent's responsibility are front-loaded, and the Args/Returns blocks are tight. The paragraph about the earlier heuristic version runs long for what it establishes, and the rhetorical framing ('a check rather than a hunch', 'decoration') costs more words than the point requires.

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

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

For a three-parameter validator with an output schema, every caller-facing question is answered: what to pass, what is validated, what the tool will not do, and what comes back. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate and does: recipe is identified as a viz_recipes.slug, mapping is a JSON role->column object with a concrete example, and columns is an optional comma-separated list whose additive checking behavior is spelled out. All three parameters gain meaning not present in the bare schema.

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

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

States a specific verb and scope: 'Check that a dataset can feed a saved recipe,' with the explicit division of labor that the agent proposes the mapping. The purpose is unmistakable, though it never names the sibling tools it borders on (find_viz, save_viz_recipe) to route the agent away from them.

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

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

Clearly frames the use case ('reproduce this with other data') and tells the agent what it must supply versus what the tool checks, plus a conditional behavior for the optional columns argument. It stops short of explicit when-not guidance or naming alternatives.

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

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

No annotations, so the description carries the full burden. 'Reads the ledger' implies a non-mutating operation and the return shape is described (counts by verdict, worst offenders first), but permissions, side effects, and what the ledger draws from are left implicit.

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

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

The rhetorical question and the '16 lessons shipped' backstory take up front-loaded space without operational content, so the definition is not front-loaded on what the tool does. The Args and Returns blocks themselves are tight and well-formed.

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

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

With an output schema present and both parameters explained, an agent has what it needs to call this correctly; the description appropriately stops short of re-specifying return fields. Only the relationship to verification tools is missing.

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

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

Schema coverage is 0%, yet the description documents both parameters meaningfully: limit as a row cap with default, and artifact as an optional path filter where omission means everything. That compensates well for the bare schema.

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

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

The opening question plus 'Reads the ledger' conveys the gist — surfacing outputs whose citations were never verified — but the actual operation is never stated as a verb+resource (e.g., 'list citation-verification debt records'). Sibling tools like verify_text_citations, verify_doi, and library_coverage overlap in domain, and nothing distinguishes this one from them.

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

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

No when-to-use guidance and no routing to alternatives such as verify_text_citations or library_coverage. The reader must infer that this is a retrospective audit query rather than the tool that performs verification.

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

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

No annotations present, so description carries full burden. It discloses no modification of original, authorization gate, and lists all supported operations with format examples. Returns expected output fields are noted.

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

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

Front-loaded with purpose, uses bullet points for operations, clearly highlights authorization. Slightly verbose but every sentence adds value.

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

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

With output schema provided, description covers all necessary behavioral and operational details: never modifies original, authorization gate, all operations, parameter semantics. Fully equips agent to use tool correctly.

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

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

Schema coverage is 0%, but description provides detailed meaning for each parameter: path (absolute path), authorized (boolean with auth flow explained), operations (list with examples), output_path (default behavior when empty).

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

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

The description states 'Apply cleaning operations to a dataset and write a new file' with a specific verb and resource. It distinguishes from siblings by focusing on execution vs. suggestion (suggest_cleaning) and other data tools.

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

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

Clearly explains never modifies original, always writes to output path, and authorization requirements. However, lacks explicit when-to-use vs. alternative tools like suggest_cleaning or profile_dataset.

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

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

With no annotations, the description carries full burden. It discloses that the tool enforces at least one decision, writes to episodic memory, and requires concrete decisions. It does not mention side effects or permissions, but provides adequate transparency 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.

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

The description is well-organized with a clear front-loaded purpose, usage note, and parameter list. It is slightly verbose but every sentence adds value. Could be slightly more concise, but still effective.

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

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

Given 4 parameters, no output schema, and no annotations, the description covers the tool's role, when to call, parameter details, and storage behavior. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema description coverage is 0%, so description must compensate. It explains the decisions parameter with examples, notes summary's optionality, describes key_topics as tags, and session_id as optional. This adds significant meaning beyond the schema structure.

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

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

The description clearly states the verb 'commit', the resource 'key decisions from this session', and explicitly distinguishes from the sibling tool 'save_session_summary' by noting its enforcement of at least one decision and separate episodic memory storage.

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

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

Provides explicit when to use: 'at the end of every agent-routed session, before delivering the final result'. Also gives an alternative tool ('save_session_summary') and explains the difference.

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

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

No annotations are provided, so description carries full burden. It explains the comparison operation and return format but does not disclose whether the tool is read-only, potential side effects, error conditions, or performance implications. Basic behavioral traits are covered but not comprehensively.

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

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

Description is concise and well-structured: first sentence summarizes purpose, then explains inputs, then outputs. Uses clear formatting with bullet points for return fields. No redundant information.

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

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

Given an output schema exists (not shown), description covers the key aspects: inputs, outputs, and usage. It could mention prerequisites (e.g., need to call profile_dataset first) but overall is adequate for a focused diff tool.

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

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

Schema coverage is 0%, yet description adds full context: each parameter (before_profile, after_profile) is described as a JSON string from profile_dataset() and explains their roles. This compensates entirely for the lack of schema detail.

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

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

Description clearly states the tool compares two dataset profiles and produces a side-by-side diff. It lists specific outputs like rows added/removed, columns added/removed, null count changes, type changes, and a human-readable summary. This distinguishes it from sibling tools such as profile_dataset.

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

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

Explicitly instructs to pass JSON strings from profile_dataset() and describes the arguments and return value. While it doesn't explicitly state when not to use or list alternatives, the usage context is clear and specific enough for correct invocation.

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

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

No annotations are provided, so the description carries the full burden. It explains provider-specific parameters and that Mendeley uses BibTeX export. However, it does not disclose whether the operation overwrites existing config, requires specific permissions, or has side effects like restarting services. 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.

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

Very concise: two sentences describing purpose, then a bulleted list of argument explanations. Every sentence adds value; no fluff. Front-loaded with the key purpose.

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

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

Given that an output schema exists (not shown), the description doesn't need to explain return values. It covers usage scenarios (setup, switching) and parameter details. It could mention validation or success indicators, but is mostly complete for a configuration tool.

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

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

Schema coverage is 0%, so the description compensates well. It explains that provider can be 'zotero' or 'mendeley', that api_key comes from a specific Zotero URL, user_id is numeric, and bibtex_path is for Mendeley. 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.

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

The description clearly states it configures the library provider for the Metis installation, with a specific verb (configure) and resource (library provider). It distinguishes from sibling tools like import_bibtex_library and sync_zotero_library which are related but different operations.

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

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

It explicitly says 'Call this during setup or when switching reference managers', providing clear context for when to use. It does not explicitly state when not to use it or list alternatives, 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.

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

No annotations are provided, so the description fully carries the transparency burden. It explains that the tool walks the folder recursively, adds files with recognized extensions to a `tracked_files` table, and includes a safety limit (max_files). This is adequate disclosure for a registration operation.

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

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

The description is concise and well-structured with a clear separation of purpose, behavior, and parameter details. It is slightly repetitive in the first two sentences, but overall efficient.

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

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

Given the moderate complexity, the description covers the tool's purpose, usage flow, parameter meanings, and behavioral constraints. An output schema exists, so return values are documented separately. It lacks error scenarios but is otherwise complete.

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

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

Schema description coverage is 0%, but the description provides detailed explanations for each parameter: folder_path (absolute path), label (short label with example), and max_files (safety limit with default). 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.

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

The description clearly states the tool's purpose: 'Register all relevant files in a project folder so Metis can read them.' It lists recognized extensions and distinguishes from the sibling tool `read_file()` by noting this is a one-time setup operation per project.

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

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

The description explicitly says 'Call this once per project; after that, use read_file() to read any individual file.' This gives clear usage context and suggests an alternative, though it does not explicitly mention when not to use it.

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

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

Despite no annotations, the description fully discloses behavior: how decisions are grouped and summarized, session summaries archived, reflexions consolidated monthly. It clarifies that originals are marked archived but still queryable, and that recall is kept fast. No contradictions with annotations (none provided).

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

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

Well-structured with bullet points and separate sections. Efficiently communicates three consolidation rules and parameter details without unnecessary words. Every sentence adds value.

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

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

Complete coverage: explains what the tool does, how it works for each memory type, parameter details, and return value (a report of actions). No gaps given the tool's complexity and parameter count.

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

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

Schema coverage is 0%, but the description compensates fully by explaining each parameter's purpose and default values in the Args section. dry_run is clearly described as a preview mode, decision_age_days and session_age_days have clear functions.

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

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

The description specifically states it consolidates old memories into monthly summaries and archives originals, with clear breakdown of three memory types. It distinguishes from sibling tools like consolidate_reflexions and consolidate_session_memory by being the comprehensive consolidation tool for all old memories.

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

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

Explicitly advises to run with dry_run=True first to preview changes. Also provides default age thresholds and explains the tiered retention behavior, giving clear guidance on when to use this tool for memory maintenance.

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

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

With no annotations provided, the description carries full burden. It discloses idempotency, deduplication, and the 7-day working memory pruning threshold. However, it omits authorization requirements or side effects like potential data loss, though the details given are substantial.

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

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

The description is extremely concise: two sentences of functional explanation plus one for idempotence. No filler, key information front-loaded. Every sentence earns its place.

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

Given 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. The description explains the core transformation (reflexions to semantic nodes, pruning) and key constraints (count threshold, dedup, window). Missing minor details like error states or performance implications, but overall sufficient for a knowledgeable agent.

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

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

Despite 0% schema description coverage, the description explains both parameters: min_count and days are directly referenced in '>= min_count times in the last `days`'. This adds meaning beyond the bare schema, though it could be more explicit about default behaviors.

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

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

The description clearly states the verb-resource pair: 'distil recurring reflexion themes into semantic memory' and 'prune working memory'. It uses specific terms like 'min_count' and 'days' to define scope, distinguishing it from sibling consolidation tools like consolidate_old_memories and consolidate_session_memory.

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

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

The description explicitly states 'Runs the nightly self-improvement consolidation', indicating it's a periodic maintenance task. While it doesn't list when not to use it or alternative tools, the context is clear enough for an agent to infer appropriate scheduling.

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

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

With no annotations, the description discloses key behaviors: reading recent runs, filtering based on output files and summaries, deduplication against existing entries, and writing to DB and markdown files. It lacks details on side effects or permissions but provides sufficient transparency 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.

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

The description is concise and front-loaded with the main action. The Args section is integrated but could be more structured (e.g., bullet points). Overall efficient with no wasted sentences.

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

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

For a tool with two parameters, high coverage in description, and an output schema (not shown), the description sufficiently explains the process, inputs, and outputs. No major gaps apparent for agent usage.

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

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

Despite 0% schema description coverage, the description's Args section explains both parameters (n_runs default 20, min_quality with options 'high' and 'all'). This adds meaningful context beyond the schema, clarifying behavior and defaults.

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

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

Description clearly states the tool scans recent agent runs, identifies high-value work, deduplicates, and writes memory entries. It specifies verbs 'scan' and 'write' with resources, and contrasts with similar siblings like 'consolidate_old_memories' and 'add_memory_entry' through its explicit workflow.

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

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

The description explains the tool reads recent runs and the meaning of parameters (n_runs, min_quality), implying use for consolidating session memory. However, it does not explicitly state when to use this vs alternatives like consolidate_old_memories or add_memory_entry, nor provides 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.

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

No annotations are provided, so the description carries the full behavioural burden. It does useful work by disclosing the write target (outputs/), the surprising default subfolder ("reviews"), format support and the return value (the written path). But for a filesystem mutation it omits overwrite/collision behaviour, permission or trust-folder requirements, and whether the directory tree is created automatically — all material for an agent writing files unattended.

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

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

Front-loaded with the action and format in the first line, followed by a single motivating sentence and a compact args block; no filler. The "Returns: The path written" line is redundant with the output schema, a minor duplication.

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

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

With an output schema present, the one-line return note is sufficient and the four parameters are fully covered. The remaining gap is behavioural rather than parametric: overwrite semantics and directory-creation behaviour are unstated for a mutation tool with zero annotation coverage.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: each of the four parameters is explained with non-obvious detail — title derives the filename, markdown headings and bullets are honoured in both formats, subdir is relative to outputs/ with default "reviews", and fmt defaults to "md" with "docx" as the alternative. An agent could not infer the filename-derivation rule or the docx markdown handling from the schema alone.

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

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

The description gives a specific verb and resource ("Write a document to outputs/") plus the two supported formats, and the phrase "the general 'save this properly' tool" positions it against more specialised writers in the sibling set such as create_presentation, create_poster and fill_document_template. It stops short of naming those alternatives explicitly, so differentiation is inferable rather than stated.

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

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

It clearly establishes when to reach for this tool: any artefact produced in a chat client that should persist beyond the transcript. What's missing is the boundary condition — nothing says when to use create_presentation/create_poster/save_review instead, or whether existing files at the same path are replaced.

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

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

With no annotations, the description carries the disclosure burden and does it well: it explains that a focus 'owns no content' and that removing it 'cannot remove anything,' which is non-obvious and directly addresses reversibility/safety. It also surfaces the 'max 3 active' constraint on activate and states what is returned. Missing only operational details like 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.

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

Front-loaded with the purpose and the key mental model, then cleanly organized into Args and Returns. Slightly discursive in the opening paragraphs, but each sentence contributes a distinct idea (scope, semantics, constraint) rather than restating the signature.

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

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

Six parameters, zero schema descriptions, no annotations — the description covers every argument, the behavioral contract (no owned content, max 3 active), and briefly the return value even though an output schema exists. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it documents all six parameters including the non-obvious one: keyword_groups is a string containing JSON, with the OR-within / AND-across semantics plus a concrete two-axis example explaining why groups rather than a flat list. That is meaning the raw schema cannot convey.

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

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

States a specific verb (define/create) and a well-bounded resource (a focus area), then immediately differentiates it conceptually from sibling concepts: 'a subject you want to stay CURRENT on, as opposed to a course you finish or a project you deliver.' An agent can tell this apart from create_project or save_course_curriculum without opening any schema.

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

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

Gives a clear selection criterion — a focus is for ongoing subjects, not finished courses or delivered projects — which implies when to reach for this rather than the project/course creation siblings. It does not explicitly name those sibling tools or say when NOT to create a focus (e.g., duplicates), so it stops short of full routing guidance.

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

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

No annotations provided, so description carries full burden. Discloses that it registers a database layer and that indexing requires a separate step. Does not mention idempotency, error behavior, or if overwriting occurs on duplicate slug. Adequate but not thorough.