research-hub

by WenyuChiou

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

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

Latest release: v1.0.2
Disambiguation5/5
Every tool has a clearly distinct purpose, with detailed descriptions that explicitly state when and when not to use each tool, eliminating ambiguity even among closely related functions like fit_check variants.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern, with predictable prefixes like 'discover_', 'fit_check_', 'notebooklm_', etc., making it easy for an agent to infer behavior from the name.
Tool Count2/5
76 tools is far beyond the typical well-scoped range; the server appears to cover a broad domain but could benefit from consolidation, as many tools are highly specialized (e.g., individual discover_* steps) and may overwhelm agents.
Completeness4/5
The tool set covers the full research workflow from discovery and ingest to analysis, labeling, cleanup, and dashboard generation. Minor gaps exist (e.g., no direct tool for deleting a cluster, relying on CLI), but core operations are well-covered.
Average 3.2/5 across 76 of 76 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 76 commits in the last 12 weeks
- Last stable release on May 26, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a write operation but does not disclose potential side effects, such as overwriting existing frontmatter, or permission requirements. With no annotations, the agent has minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is too brief for a tool with two parameters and nested objects. It sacrifices necessary detail, making it insufficiently informative for correct usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and nested parameters, the description omits crucial context like output format, behavior on existing data, error handling, and usage workflow. It fails to provide a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters 'cluster_slug' or 'assignments'. The agent cannot infer their meaning or structure, especially with a nested object type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (write) and target (subtopics frontmatter to each paper note). It distinguishes from sibling tools like 'propose_subtopics' which generates subtopics, but could be more explicit about the context of cluster usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'propose_subtopics' or 'apply_cluster_summaries'. The description lacks any context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'upload' without disclosing side effects, required authentication, or behavior of parameters like dry_run and create_if_missing. The term 'saved session' hints at a prerequisite but is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is underspecified given the tool's complexity (4 parameters, no param docs). Conciseness should not sacrifice essential information; here it is too terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of 4 parameters, no annotations, and an output schema (content unknown), the description fails to provide necessary context such as what a 'cluster bundle' is, what a 'saved session' entails, or how to obtain the required inputs. The tool appears to be a mutation with side effects but lacks sufficient detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no information about any of the four parameters. The agent is left to infer meaning from names alone (cluster_slug, dry_run, headless, create_if_missing), which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uploads the latest cluster bundle to NotebookLM using a saved session, specifying the verb (upload) and the resource (cluster bundle to NotebookLM). It is specific enough to convey the action, though it does not differentiate from sibling tools like notebooklm_bundle or notebooklm_generate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any prerequisites or exclusions. The description simply states what it does without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states the basic action and omits critical details: return format, pagination, behavior of optional parameters (cluster, status), and whether modifications occur. This is severely insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it sacrifices essential information for brevity. It is under-specified given the tool's parameter complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which need not be described), the description lacks details about parameter behavior and usage context. For a tool with 4 parameters, this is far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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 only alludes to 'full_text' via 'by title or full text', but provides no meaning for 'query', 'cluster', or 'status'. The added value beyond the schema is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches 'local vault notes' by 'title or full text', specifying the resource and scope. It distinguishes from sibling tools like 'search_papers' which target papers, not vault notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention any conditions, exclusions, or comparisons to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a 'view', implying read-only behavior, but does not explicitly confirm idempotency, side effects, or whether it requires authentication. The description adds minimal behavioral context beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. It is front-loaded with the tool's purpose and lists key content areas. However, it could be slightly more structured (e.g., listing what the output includes) without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description could omit return details, but it does not mention the tool's scope (e.g., whether it covers all clusters or suggests actions). With only one parameter and no nested objects, the description is still too sparse to fully guide correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'cluster_slug', lacks any description in the schema (0% coverage) and the tool description provides no explanation of what constitutes a valid slug, its purpose, or formatting. The agent has no guidance on constructing this parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Aggregate maintenance view' suggests a read-only overview but lacks an explicit verb (e.g., 'get', 'list'). It lists covered areas (staleness, scope drift, etc.) but does not clearly differentiate from sibling tools like 'read_crystal' or 'show_cluster' that may provide similar views.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not specify prerequisites, when to invoke it, or when not to. Given the large set of sibling tools, this omission reduces usability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden. It does not disclose any behavioral traits like error handling (invalid DOI), rate limits, or side effects. The description is too sparse for an agent to understand implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but at the expense of necessary detail. It front-loads the action but is too brief to be informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, output schema exists), the description should at least clarify parameter formats and purpose. It fails to do so, leaving the agent with insufficient context despite the output schema existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to parameters. 'doi_or_slug' and 'style' are undefined; valid styles are not enumerated. The agent has no clue what values are acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns an inline citation string for a paper, making the action clear. However, it lacks differentiation from sibling tools like 'get_citations' or 'export_citation'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, such as when an inline citation is needed vs. a full reference list. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says it generates files, implying writes, but does not disclose whether it overwrites existing files, requires specific permissions, or has side effects. No annotations are provided to compensate, leaving behavioral traits unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded, but it sacrifices critical information. It could be expanded to include parameter explanation and behavioral notes without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to explain the output format or what the generated files contain. The parameter is not described, and the tool's role among siblings is unclear. The description is incomplete for a tool with one parameter and an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'cluster_slug' is entirely undocumented in the description. With 0% schema description coverage, the description should explain the parameter but does not. The mention of 'paper frontmatter' does not clarify what cluster_slug represents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates topic note files from paper frontmatter. The verb 'Generate' and resource 'topics/NN_<slug>.md files' are specific, and it distinguishes from sibling tools like list_topic_notes or write_topic_overview. However, the meaning of 'NN_' is ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like list_topic_notes or write_topic_overview. The description does not specify prerequisites, exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states what the tool does, not side effects, permissions, or whether it is read-only or destructive. For a tool that likely creates a draft, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary structure. While front-loaded with the core action, it omits critical details that would fit in a slightly longer description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (assembling draft from multiple sources) and the presence of an output schema and siblings like 'compose_draft', the description is too terse. It fails to explain how parameters affect output or when to prefer this over similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (cluster_slug, outline, max_quotes) with 0% schema description coverage. The description does not explain any parameter, leaving the agent to guess their meaning and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: assembling a markdown draft from specific sources (cluster quotes, overview, crystal TLDRs). This verb-resource pair is specific and distinct from many siblings, though it does not explicitly differentiate from 'compose_draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like 'compose_draft' or other drafting tools. The description does not provide context for appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states the action ('assemble') but does not disclose whether the operation is destructive, idempotent, or whether it interacts with existing drafts. The required cluster_slug hints at context but is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but insufficient for a tool with 5 parameters and nuanced behavior. Important details are omitted, making it underspecified rather than efficiently brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description fails to cover prerequisites, expected inputs, or output details. It does not explain the role of the cluster, how the outline affects the draft, or the meaning of the style parameter. The tool's relationship to other composition tools is unclear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must elaborate on parameters. It only implies 'captured quotes' (mapping to quote_slugs) and 'draft' (output format). The other parameters (cluster_slug, outline, style, include_bibliography) are completely unmentioned, leaving their roles ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states its purpose: assembling captured quotes into a markdown draft. It specifies the resource ('captured quotes') and output format ('markdown draft'). However, it does not differentiate from the sibling tool 'compose_brief_draft', which could have distinct functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. For example, 'compose_brief_draft' is listed as a sibling but no distinction is made. Prerequisites (e.g., existence of captured quotes and a cluster) are implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavioral traits. It only says 'emit', implying a generation operation, but does not disclose whether it is read-only, requires permissions, has side effects, or what the output format is. The lack of transparency 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but sacrifices detail. It is front-loaded but underspecified. An appropriately sized description would include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fails to explain the output (despite an output schema existing), the role of parameters, or the overall workflow. Given the complexity of generating a prompt for crystal generation, more context is needed for the agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description provides no explanation of the parameters (cluster_slug, question_slugs). The description does not compensate by adding meaning beyond the parameter names, leaving the agent to guess their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it emits a markdown prompt for generating crystals, which is a specific verb+resource. However, the phrasing is somewhat convoluted ('the calling AI should answer to generate crystals') and lacks clarity on what the prompt is for. It distinguishes from siblings like emit_assignment_prompt but could be more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives (e.g., emit_assignment_prompt), nor does it specify prerequisites, context, or exclusions. This leaves the agent without guidance on proper invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits like read-only or idempotency. It only implies a read operation ('resolve') but does not confirm side effects, error handling, or network dependency. The agent gets minimal insight into tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise but underspecified. For a tool with 2 undocumented parameters, it fails to include essential information, making it closer to under-specification than efficient conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description omits crucial context about input semantics and behavior. With 0% schema coverage, the description should compensate but does not, leaving the tool incomplete for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation for the 'candidates' or 'backends' parameters. The agent has no clue what candidate identifiers are (e.g., DOIs, IDs) or what backends represent, which critically undermines correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (resolve) and the resource (candidate identifiers to full paper records), making the tool's purpose specific. It distinguishes from siblings like 'search_papers' by focusing on resolution of candidates rather than general search, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'search_papers' or 'verify_paper'. The description lacks context for appropriate usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions writing a rejected sidecar, implying mutation, but lacks details on side effects, permissions, error handling, or the nature of the sidecar. Very minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but at the expense of clarity. It could benefit from structure, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 4 parameters (3 required) and an output schema, the description fails to explain the filtering logic, the 'sidecar' concept, or provide context for the tool's internal workings. Significant gaps remain given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions coverage is 0%, and the description does not explain the parameters ('cluster_slug', 'candidates', 'scores', 'threshold'). The terms 'AI scores' and 'candidates' are used but not mapped to the schema. No added meaning beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool consumes AI scores, filters candidates, and writes a rejected sidecar, giving a rough idea of the operation. However, 'sidecar' is undefined and the description does not differentiate from sibling tools like fit_check_audit or enrich_candidates, so clarity is moderate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor are prerequisites or conditions mentioned. The agent receives no context about appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states what the tool builds, but does not reveal whether the prompt is stored, returned, or has side effects. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks substance. It does not front-load key information beyond the purpose. While brevity is appreciated, the description would benefit from additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. However, with 0% parameter coverage and missing usage guidance, the description fails to provide a complete understanding for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the three parameters (cluster_slug, candidates, definition). Without any guidance, the agent cannot determine how to correctly populate these fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool builds a Gate 1 fit-check prompt for an AI to score. It uses a specific verb ('Build') and identifies the resource ('Gate 1 fit-check prompt'). While it doesn't explicitly differentiate from siblings like fit_check_apply, the purpose is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as fit_check_apply or fit_check_audit. There is no indication of prerequisites, context, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It only says 'set, add, or remove labels' without detailing behavioral traits like whether setting replaces all labels, what happens with duplicates, or how fit_score/fit_reason interact. The mutation aspect is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, it is too vague and does not earn its place by informing the agent adequately. It could be expanded to cover critical aspects without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no annotations, and an output schema (but not referenced), the description is incomplete. It omits how fit_score/fit_reason are used, what the output contains, and any usage constraints. A minimal description for a complex label manipulation tool should do more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It mentions nothing about 'slug', 'labels', 'add', 'remove', 'fit_score', or 'fit_reason'. Parameter names provide some hint, but the description does not map them or clarify how they work together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (set, add, remove) and the resource (labels on a paper note). It distinguishes the tool's purpose from sibling tools that deal with paper existence or clustering. However, it doesn't differentiate among the three operations or explain when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like 'mark_paper' or 'apply_fit_check_to_labels'. The description does not mention prerequisites, context, or when to use set vs add vs remove.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only says 'Trigger... generation' without indicating whether the operation is destructive, asynchronous, or requires specific permissions. The agent cannot anticipate side effects or state changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks necessary detail. It is front-loaded but too brief for a 3-parameter tool with no schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of sibling tools and lack of schema descriptions, the description is incomplete. It does not clarify what 'artifact generation' entails, how it differs from similar tools, or what the output schema provides.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It does not mention cluster_slug, artifact_type, or headless at all. The agent has no semantic guidance beyond parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Trigger' and the resource 'NotebookLM artifact generation for a cluster notebook'. It is specific but does not differentiate from siblings like notebooklm_bundle or compose_brief_draft. The purpose is clear at a high level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., compose_brief_draft, notebooklm_bundle). There is no mention of prerequisites or typical use cases, leaving the agent to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose whether the tool creates side effects (e.g., storing the prompt) or is read-only. The agent cannot infer safety or persistence from the description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it sacrifices crucial details for brevity. It does not fulfill the need to differentiate among 70+ sibling tools or explain parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits essential context like the relationship to subtopics, the role of the parameters, and how the prompt will be used. For a tool with many similar siblings, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention either parameter ('cluster_slug' or 'target_count'). The agent must guess their meaning from names alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Build' and identifies the resource as 'Phase 1 sub-topic proposal prompt', with a clear consumer ('for an AI to consume'). This distinguishes it from sibling tools like 'propose_research_setup' but could be more explicit about the prompt's content or purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'suggest_cluster_split' or 'plan_research_workflow'. The description lacks context about the phase in a workflow or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral context. It does not disclose search mechanics, rate limits, authentication requirements, or result structure, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (6 words), which is concise, but it lacks sufficient detail for a complex tool. It is not overly verbose, but under-specification reduces its value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters and an output schema, the description is incomplete. It does not explain how parameters interact, filtering behavior, or search semantics, leaving the agent to infer from parameter names alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
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, but it adds zero parameter details. Even though many parameters have defaults and names, their meaning and usage are not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and resource 'academic papers', with mention of 'multiple backends' distinguishing it from general search tools like web_search. However, it lacks specificity about which backends or how results are aggregated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as web_search or search_vault. The description does not mention prerequisites, exclusions, or situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It indicates the tool suggests and finds but does not state whether it modifies state, requires authorization, or has any side effects. Minimal behavioral context is provided beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (12 words), but it omits important details about parameters and usage. It is efficient but under-specified for practical use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values are covered, but the description fails to sufficiently detail the purpose and behavior of the three input parameters. The description is incomplete for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description adds no explanation for the parameters (identifier, top_clusters, top_related). This forces the agent to infer meaning from names alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suggests a cluster for a paper and finds related papers, using specific verbs and resource references. However, it does not explicitly differentiate from sibling tools like suggest_cluster_split or search_papers, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as search_papers or suggest_cluster_split. The description lacks context about appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond the core action. It does not disclose side effects (e.g., file creation, metadata updates), permissions needed, error handling, or any constraints. Without annotations, the agent has insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief (one sentence) but fails to convey essential information. It is underspecified rather than concise, lacking detail that is necessary for effective tool selection and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of parameter descriptions, usage guidance, and behavioral transparency, the description is severely incomplete. The existence of an output schema does not compensate for the lack of input and usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the three parameters ('folder', 'cluster_slug', 'dry_run'). With 0% schema description coverage, the agent cannot infer the meaning, format, or purpose of these inputs beyond their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'walk and ingest' targeting a resource 'local folder' and 'non-DOI files', clearly indicating what the tool does. It differentiates from siblings by implying it handles folder ingestion, which is distinct from other sibling tools like 'add_paper' or 'search_papers'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. There is no mention of prerequisites, exclusions, or comparison to other import or ingestion tools among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies destructive behavior ('Remove') but does not disclose side effects, reversibility, or prerequisites. With no annotations, the description carries full burden and fails to inform about safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but lacks important details. Could be more informative while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and output schema, but missing explanation of return value, success/failure behavior, or side effects. Incomplete for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'for a cluster' but does not explain the cluster_slug parameter beyond general scope. Schema coverage is 0%, and description adds minimal meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Remove' and the resource 'discover stash directory' scoped to a cluster. It distinguishes from siblings like discover_new or discover_status by indicating a cleanup action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like discover_new or when cleanup is appropriate. The agent lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the function but does not disclose idempotency, side effects, or that it is a read-only operation. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficient but too brief, missing essential details. It is front-loaded but at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool has only one parameter and an output schema exists, the description lacks context about how to find the cluster slug or what to expect in return. Adequate when combined with other tools, but incomplete standalone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'cluster_slug' has no description in the schema, and the tool description does not explain its meaning, format, or how to obtain it. With 0% schema coverage, the description adds no value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists sub-topic notes for a cluster, with a specific verb and resource. It distinguishes from siblings like build_topic_notes (creates) and list_clusters (lists clusters). However, 'sub-topic notes' could be more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions. The description fails to provide context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral information. It does not disclose side effects, authorization needs, or what the output represents beyond 'build'. The agent cannot tell if this triggers uploads or modifies state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. However, it is at the edge of being too terse, sacrificing necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a simple parameter set and an output schema, the description lacks essential context: what is a bundle, when to build vs. upload, and how the output is used. It is incomplete for a tool with many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not reference the two parameters (cluster_slug and download_pdfs) at all. With 0% schema description coverage, the description should compensate but fails to explain how each parameter affects the bundle.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Build) and the resource (NotebookLM upload bundle) with context (for a cluster). It distinguishes itself from sibling tools like notebooklm_upload and notebooklm_download, but could be more specific about the bundle contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives such as notebooklm_upload or notebooklm_generate. The description lacks any contextual hints about prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must compensate, but it lacks details on behavior: what happens if no artifact exists, permissions needed, whether it overwrites or creates new files? Does not explain parameters like 'headless' or 'artifact_type'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, which is concise but lacks necessary detail. It front-loads the main action but sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters with no schema descriptions, no annotations, and an output schema (unseen), the description is severely incomplete. It does not explain usage context, output, or prerequisites, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description should explain parameters. However, only 'briefing artifact' is mentioned; 'cluster_slug', 'artifact_type', and 'headless' are not described, adding no meaning beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'download' and resource 'latest NotebookLM briefing artifact' with destination 'into the vault'. It distinguishes from siblings like notebooklm_generate (generates) and notebooklm_upload (uploads).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., notebooklm_generate, notebooklm_upload, notebooklm_bundle). No information on prerequisites or conditions like artifact existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description lacks details on side effects (e.g., duplicate handling, state changes), authentication requirements, or rate limits. 'Ingest' is vague and does not disclose potential behaviors like skipping existing papers or triggering downstream processing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but at the expense of necessary detail for 4 parameters. It is concise but insufficient for comprehensive understanding, missing parameter explanations and usage nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return value explanation is not required. However, with 4 parameters and no annotations, the description fails to cover parameter roles or behavioral context, leaving the tool underspecified for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description explains only the 'identifier' parameter as DOI/arXiv ID but ignores 'cluster', 'no_zotero', and 'skip_verify'. Their purposes remain unclear, forcing reliance on parameter names and defaults alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a paper by DOI/arXiv ID and ingests it, specifying the action and resource. It distinguishes from sibling tools like 'search_papers' which search by query, but does not explicitly differentiate from other import tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'import_folder_tool' or 'search_papers'. The description only states the basic operation without context of prerequisites or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose side effects. It mentions persisting to a file but does not explain overwrite behavior, error handling, or any required context (e.g., directory existence).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but lacking structure. It could be expanded with parameter details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description omits behavioral context such as idempotency, required permissions, or return value semantics. The tool has 4 parameters with 0% schema coverage, yet the description does not compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides zero explanation for the four parameters (slug, page, text, context). The agent cannot infer their meaning or format from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (persist a quote) and specifies the exact file path in the vault, distinguishing it from other tools that list or manage quotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like add_paper or list_quotes. No prerequisites or when-not-to-use scenarios mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description merely states it 'checks how many crystals are stale,' implying a read operation but offering no details on side effects, resource consumption, or response format. Behavioral insight is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and without wasted words, but it sacrifices necessary detail (e.g., parameter explanation). It is concise but insufficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks essential information about the required parameter and does not clarify what the output schema provides. For a tool with one parameter and no schema descriptions, the description is incomplete to enable correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the required 'cluster_slug' parameter at all. The agent receives no guidance on what values are valid or how the parameter affects the tool's behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (check), resource (crystals), and condition (>10% delta since generation). It distinguishes from siblings like 'list_crystals' (list all) and 'read_crystal' (read specific), providing a specific monitoring function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives. The description implies usage for staleness checks but does not mention scenarios where other tools (e.g., list_crystals, read_crystal) would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description mentions 'stashing state' but does not disclose any behavioral traits such as side effects, authorization needs, rate limits, or whether it modifies data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one sentence and lacks structure. For a tool with 20 parameters, it is under-specified and should be more detailed or use bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (20 parameters, no annotations), the description is woefully incomplete. It does not explain return values (even though output schema exists), parameter relationships, or how the tool fits with other siblings beyond discover_continue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any of the 20 parameters (e.g., cluster_slug, query, year_from), leaving the agent without guidance on their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a search and emits a fit-check prompt, stashing state for discover_continue. This distinguishes it from sibling tools like discover_continue and discover_variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that after running discover_new, one should use discover_continue, but it does not provide explicit guidance on when to use this tool versus alternatives, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behavior. It mentions 'emit (or refresh)' but does not explain whether it overwrites, side effects, authorization needs, or any destructive potential. This is insufficient for a file-related operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it omits necessary details about parameters and behavior. While concise, it lacks completeness, making it borderline under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity (2 params, output schema present), the description fails to explain the role of 'force', the nature of the output, or any effects. An output schema exists but is not referenced; the agent lacks context for decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to 'cluster_slug' or 'force'. Without any explanation of parameters, the agent cannot infer their purpose beyond type hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool emits or refreshes a .base dashboard file for a cluster, using a specific verb and resource. It distinguishes itself from siblings like 'generate_dashboard' or 'emit_crystal_prompt' by specifying the entity type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. Given many sibling tools (e.g., 'generate_dashboard'), the description lacks context for choosing this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only status, pagination, or rate limits. It merely states the action without context on side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded, consisting of a single sentence. While brevity is valued, the lack of additional detail may hinder understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema, the description is minimally complete for a list tool. However, it lacks context on input format, error handling, and typical use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning to the parameters. It does not explain what 'identifier' represents (e.g., DOI, paper ID) or how 'limit' affects results. With 0% schema description coverage, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing papers cited by a given paper (its bibliography). However, it does not differentiate this from sibling tools like get_citations, which may retrieve papers that cite the given paper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention which papers qualify as 'references' or how it differs from get_citations, search_papers, or web_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It fails to mention important traits like read-only nature, permission requirements, pagination, or what exactly 'paper states' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it is too brief and lacks critical detail, making it less useful despite conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters (no schema descriptions), no annotations, but an output schema, the description leaves many unknowns (e.g., what 'paper states' are, how filters combine, output format). Insufficient for effective tool selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should compensate. It only mentions 'filtered by label' but doesn't clarify the difference between 'label' and 'label_not' or explain 'cluster_slug'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns paper states for a cluster with optional label filtering, which is clear. However, 'paper states' is somewhat vague and doesn't distinguish from sibling tools like 'list_clusters' or 'search_papers'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There are many sibling tools for listing, filtering, or labeling papers, but the description provides no selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details beyond the basic read operation. Without annotations, it does not disclose side effects, permission requirements, or constraints. The read-only nature is implied by the name but not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, with only one sentence. It front-loads the action and immediately provides parameter guidance. However, it could be slightly expanded for completeness without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal given the tool has three parameters and an output schema. It fails to set context about what cluster memory is, what the output looks like, or any important caveats. The output schema may compensate, but the description should provide a higher-level understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain all parameters. It only explains the 'kind' parameter values but omits the meaning of 'cluster' and 'min_confidence', leaving the agent with incomplete parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads cluster memory and specifies the 'kind' parameter values, which helps the agent understand the resource and action. However, it does not differentiate this tool from similar sibling tools like 'read_crystal' or 'show_cluster', leaving potential ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or when not to use it, leaving the agent without decision-making support for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the persistence action but does not specify whether existing files are overwritten or appended, permission requirements, or error handling. This is insufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the key action and destination. Every word earns its place; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 and nested objects, the description omits details on return format, handling of crystals_json structure, and error conditions. It is not complete enough for an agent to invoke correctly without assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description gives no explanation of the two parameters (cluster_slug, crystals_json). The description adds no meaning beyond the schema, failing to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool persists crystal answers to a specific file path (hub/<cluster>/crystals/<slug>.md), which is a clear verb+resource. However, it does not define what 'crystals' are or differentiate from siblings like 'apply_cluster_summaries' which also persist data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives like 'apply_cluster_summaries' or 'emit_crystal_prompt'. The description does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully convey behavioral traits. It only says 'return', implying a read-only operation, but does not clarify permissions, side effects, or the nature of 'discover state'. This is insufficient for sound agent reasoning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, which is very concise. However, it is under-specified; conciseness should not come at the cost of completeness for a tool with no other documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 parameter, output schema exists), the description is minimally adequate but fails to clarify what 'discover state' entails or how the output should be interpreted. The presence of an output schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'cluster_slug' has 0% schema description coverage and is not explained in the description. The agent receives no guidance on its format, source, or meaning beyond the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return' and the resource 'current discover state for a cluster'. It is specific and distinguishes from sibling tools like 'discover_new' or 'discover_continue' which initiate or modify discovery processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., when to check state vs. when to start discovery). There is no mention of prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description minimally discloses behavior: it lists pre-computed answers. Does not reveal if results are paginated, ordered, or if errors occur for invalid cluster_slug.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is direct and to the point. No wasted words, but could be slightly expanded for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema which reduces burden, but description doesn't address pagination, error handling, or whether the list is sorted. Minimal but adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for the single parameter. It only implies cluster_slug identifies the cluster, but no details on format, constraints, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (List) and resource (pre-computed crystal answers) with scope (for a cluster). Differentiates from sibling list tools like list_clusters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 siblings like read_crystal or list_clusters. Lacks any when-not or alternative usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose important behavioral traits such as side effects (e.g., physical file movement), required permissions, or error conditions. The mention of delegation to an internal function is not helpful for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with the main action, but it lacks necessary details. While concise, it is underspecified, scoring average.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema details, the description is incomplete. It does not cover behavioral expectations, return values, or usage scenarios, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra meaning beyond what the schema already provides; it remains neutral.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move a paper note') and the resource ('from its current cluster to another'). It is specific about what the tool does, though it does not explicitly differentiate from sibling tools like 'collect_to_cluster' or 'merge_clusters'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'add_paper' or 'remove_paper'. No usage context or preconditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It states 'Read' implying a safe, read-only operation, but does not explicitly confirm this or mention any other behavioral traits (e.g., idempotency, rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise but too terse. It lacks structure such as parameter explanations or usage examples. It conveys purpose but fails to earn its place by omitting critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool with three parameters and an output schema. It does not explain the parameters sufficiently, especially 'level' with its default. While output schema may handle return values, the input side is underdescribed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only vaguely references 'detail level' for the 'level' parameter. It does not explain the meaning of 'cluster_slug' or 'crystal_slug', nor does it clarify valid values or the default for 'level'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'crystal', immediately distinguishing this from siblings like 'list_crystals'. The mention of 'detail level' hints at the 'level' parameter, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference siblings like 'list_crystals' for listing all crystals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states it writes a file, but omits crucial details: the overwrite parameter's default behavior (false), whether the operation is destructive, required permissions, or any side effects. This is insufficient 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise and front-loaded. However, it is under-specified for the tool's complexity, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no annotations, and an output schema that presumably explains return values, the description still lacks key contextual information: the meaning of 'cluster_slug,' the expected format of 'markdown,' and the behavior of 'overwrite.' This is insufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no meaning to the parameters. The parameters 'cluster_slug,' 'markdown,' and 'overwrite' are not explained at all. The description fails to clarify what each parameter represents or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write a topic overview markdown file for a cluster,' using a specific verb (write) and resource (topic overview). It effectively distinguishes from the sibling tool 'read_topic_overview,' which is for reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or any context that helps an agent decide between this and sibling tools like 'apply_cluster_summaries' or 'summarize_cluster.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only labels the operation as 'copy' but omits important details like whether it duplicates an existing example, what happens on conflict, permissions needed, or side effects on related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action. Every word is necessary and there is no superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values are covered. However, the description lacks completeness for a simple copy tool: it doesn't explain what an 'example' is, what the 'cluster registry' is, or how the tool integrates with sibling tools like examples_list. The two parameters are not contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain the meaning or constraints of the two parameters ('name' and 'cluster_slug'). The agent has no way to infer what values are valid or how they affect the copy operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Copy'), the object ('an example'), and the destination ('into the user's cluster registry'). It distinguishes this tool from siblings like examples_list and examples_show by indicating a mutation operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. For a copy operation, it would be helpful to mention if the source example must exist or if overwriting occurs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the output formats but does not disclose whether the tool is a read operation, requires network access, or has any side effects. Missing details on error handling or input dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb 'Export', and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three optional parameters and multiple formats, the description is too sparse. It fails to explain the roles of identifier and cluster, and does not mention the output schema or return value, though an output schema exists externally.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It clarifies the format parameter by listing specific values, but does not explain identifier or cluster parameters. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports a citation in specific formats (BibTeX, BibLaTeX, RIS, CSL-JSON). It uses a specific verb and resource, distinguishing it from siblings like build_citation or get_citations, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided about when to use this tool versus alternatives like build_citation or get_citations. There is no mention of prerequisites, conditions, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the tool returns data and a digest, with no mention of side effects, permissions, or output format details. This is insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, front-loaded with the action and result. It is concise but may be too brief, missing important details about the digest and parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotation support and a single undocumented parameter, the description fails to provide adequate context. The existence of an output schema partially compensates, but the input parameter and behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'cluster_slug' has no description in the schema (0% coverage). The tool description adds no explanation of what a cluster_slug is or how to obtain it, leaving the agent without required context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every paper in a cluster plus a markdown digest for overview writing. This distinguishes it from sibling tools like 'show_cluster' or 'summarize_cluster' by emphasizing the digest generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as 'show_cluster' or 'summarize_cluster'. The description does not provide context about prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies mutation but does not disclose side effects, permission requirements, or error handling beyond what the schema provides. The second sentence is an implementation detail, not a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose. However, the second sentence is unnecessary for tool selection (delegation detail) and could be removed to improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's mutation nature and the presence of many sibling tools, the description lacks completeness. It should mention idempotency, what happens on error, or reference the output schema. The current description is too sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description does not add extra meaning beyond what is in the schema, thus baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the reading status of a paper note,' which specifies the verb (update) and resource (reading status of a paper note). It distinguishes from sibling tools like add_paper and remove_paper, though it could be more explicit about what exactly it updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description only mentions delegation to an internal function, which is not helpful for deciding when to use this tool versus alternatives like label_paper or move_paper.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It implies a read-only analysis via 'suggest', but does not explicitly confirm no side effects or state permissions. The presence of an output schema aids expectations, but transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, correctly front-loaded sentence with no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters and no param descriptions, the tool requires more context on how the analysis works and what the output contains. The description does not address the output schema or parameter effects, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain any parameters. 'cluster_slug' is required but undefined; 'min_community_size' and 'max_communities' have defaults but no role. The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'analyze' and 'suggest' with the resource 'cluster's citation graph' and 'sub-topic splits'. It distinguishes from siblings like 'split_cluster' (which performs the split) and 'propose_subtopics' (which may not use citation graph).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs. alternatives like 'split_cluster' or 'propose_subtopics'. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the removal action and optional Zotero deletion, but does not elaborate on destructive nature, reversibility, permissions, side effects, or how dry_run works. This is minimal transparency for a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the core functionality without any extraneous words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (3 parameters, 1 required) and presence of an output schema, the description covers the main action and one parameter but misses dry_run behavior and identifier format. It is adequate but has clear gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must add meaning. While 'optionally deleting its Zotero item' hints at the include_zotero parameter, it does not explain the required identifier (e.g., paper ID format) or the dry_run parameter, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'remove' and the resource 'paper from the vault', with an optional Zotero deletion, making the purpose unambiguous. It implicitly distinguishes from sibling tools like add_paper, move_paper, and mark_paper, as removal is a distinct action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided; the description does not specify when to use this tool versus alternatives like move_paper or mark_paper. There is no discussion of prerequisites, confirmation steps, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the action without explaining whether the tool is read-only, if it modifies state, or what the output format is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema exists), the description is minimally adequate but lacks information about side effects, permissions, or expected output, which an agent might find useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (empty schema) and there are no parameters, so the description adds no parameter info. Baseline 3 is appropriate as no additional meaning is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Run health checks') and the resource ('research-hub installation'), distinguishing it from sibling tools which focus on paper management, clustering, and other tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as for troubleshooting or periodic maintenance. There are no hints about prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose whether the split is destructive, if papers are removed from source, or how the new cluster is formed. Lacks essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key action. Efficient but could benefit from structured breakdown of parameters and behavior. Not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 required parameters and no schema descriptions, the description should explain each parameter and the effect on clusters. It only provides high-level purpose, missing details needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description adds meaning that 'query' relates to title keyword overlap, but does not explain 'source' and 'new_name' beyond their names. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (split), resource (cluster), and mechanism (title keyword overlap). It distinguishes from sibling tools like merge_clusters or prune_cluster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for splitting based on title keyword overlap but does not specify when not to use it or mention alternatives like suggest_cluster_split. No explicit guidance on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states 'verify', which implies a read operation, but does not detail side effects, return format, or error handling. The presence of an output schema mitigates some lack, but the description itself is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and methods. Every word carries weight, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 optional parameters and no annotations, the description is too brief. It does not address how parameters interact (e.g., combined usage), what happens on success/failure, or the output schema content. The presence of an output schema helps, but the description alone leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 adds meaning for 'doi', 'arxiv_id', and 'title' via 'DOI, arXiv ID, or fuzzy title match', but entirely ignores 'authors' and 'year' parameters. This incomplete coverage reduces clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'verify' and the resource 'paper', and specifies the methods (DOI, arXiv ID, or fuzzy title match). It effectively distinguishes from sibling tools like 'search_papers' (full search) and 'add_paper' (creation), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for confirming existence of a paper using identifiers, but it does not explicitly state when to use it versus alternatives (e.g., search_papers). It lacks guidance on when not to use it or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully convey behavior. It indicates a read-only operation, but omits authentication needs, error handling, pagination, or ordering. The description is minimal for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words; information is front-loaded and efficiently conveys the tool's action and optional parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description provides basic functionality. However, it lacks guidance on output content (though output schema exists), ordering, or relationship to other entities like clusters, which could improve usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds context by stating the cluster_slug parameter is optional and used for filtering. This clarifies the parameter's purpose, though it could further explain what a cluster_slug represents or how to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists captured quotes with optional cluster filtering. It distinguishes from sibling tools like capture_quote (create) and list_clusters (lists clusters), but does not explicitly differentiate from other list tools like list_crystals or list_papers_by_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage: retrieve quotes, optionally filtered by cluster. No explicit guidance on when not to use or alternatives among sibling list tools, leaving inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose any behavioral traits such as read-only nature, side effects, or authorization requirements. For a tool with no annotations, the description should add transparency beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with all key information front-loaded. No extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered. However, the description lacks context about slug provenance, error handling, and whether the cluster must exist. It is minimally sufficient but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain what 'slug' means. Although it is a single parameter, its format and how to obtain it are not clarified, leaving ambiguity for an AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Show'), the resource ('cluster'), and specifies 'detailed info including sync status'. This distinguishes it from siblings like list_clusters (listing) and summarize_cluster (summary).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Context is implied but not stated, and there are no prerequisites or when-not-to-use indicators.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the core behavior (persisting to Obsidian+Zotero) and payload shape, but does not disclose side effects, auth needs, or overwrite behavior. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding value. No redundant information. Efficiently communicates purpose and payload constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. But description lacks details on merge/overwrite behavior, prerequisites, or error handling. Adequate for basic understanding but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It clarifies summaries_json as 'payload of per-paper summaries' with shape `{summaries: [...]}`, but provides no additional info for cluster_slug. Partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Persist' and targets 'Obsidian + Zotero', clearly stating what the tool does. However, it does not explicitly differentiate from sibling tools like apply_crystals, leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions usage context ('when LLM was invoked out-of-band') and references the summarize_cluster prompt, implying when to use it. But it lacks explicit when-not or alternative tools, so guidance is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond 'list all'. It does not mention that the operation is read-only, nor does it address pagination or performance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown), the description need not detail return values. However, with many sibling tools, additional context such as 'this is a read-only operation' would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and schema description coverage is 100%. The baseline for 0 parameters is 4, and the description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('all topic clusters'), and what is included ('their bindings'). This differentiates from sibling tools like 'show_cluster' which likely returns details of a single cluster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'show_cluster' or 'summarize_cluster'. The agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly states that the source cluster is deleted after merge, indicating destructive behavior. With no annotations, this disclosure is adequate, though it could mention idempotency or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences; the first is effective but the second mentions internal delegation which is unnecessary for tool selection. Could be more focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the basic operation but lacks mention of error conditions, what happens if clusters do not exist, or the output format (though output schema exists). Adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have comprehensive schema descriptions (100% coverage). The tool description adds no new information beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: merge all papers from one cluster into another and then delete the source. This distinctively differentiates from sibling tools like split_cluster or prune_cluster.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like split_cluster or simple_move. Does not mention prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose any behavioral details beyond listing (e.g., read-only, no side effects). Agent must infer safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise—three words—and front-loaded with verb and resource. No wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema, the description is minimally adequate. Could mention output format (e.g., list of names), but schema fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% trivially. Description adds no param info but none is needed. Baseline is 4 per rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and the resource 'bundled example clusters', which is specific and distinguishes it from siblings like 'examples_copy' and 'examples_show'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as 'examples_copy' or 'examples_show'. The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only notes delegation to Semantic Scholar, omitting details like rate limits, authentication, or that it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the purpose and adding a technical note. Every sentence is meaningful and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, the description covers the identifier format and delegation. An output schema exists, so return values need not be explained. Minor gaps in usage context remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions, but the description adds 'Bare titles are NOT accepted,' which provides extra clarity beyond the schema's parameter types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List papers that cite the given paper') and specifies 'forward citations' to differentiate from backward citation tools like 'get_references'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus siblings like 'get_references' or 'search_papers'. It only mentions delegation to an API.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'Show,' indicating a read operation, but does not mention any side effects, authentication needs, or limitations. More detail about what exactly is shown (e.g., file paths, environment settings) would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loading the action and resource. It contains no extraneous words and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description is largely adequate. However, it could be slightly more complete by clarifying the scope of 'configuration paths and settings' (e.g., system-wide or user-specific). Nevertheless, it is sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, so the description does not need to explain any. The baseline for 0 parameters is 4, and the description appropriately avoids adding unnecessary parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Show' and clearly identifies the resource: 'current configuration paths and settings.' This unambiguously states what the tool does, and there are no sibling tools with similar names, so differentiation is not needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no context for usage, and no exclusions. While it's a simple read-only tool, the lack of any usage direction is a gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description hints at optional return via 'if present' but does not disclose the exact behavior when no overview exists, permissions, or side effects. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste. It is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, one parameter, and existing output schema, the description is minimally viable but could clarify the parameter's format or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the single parameter 'cluster_slug', and the schema has 0% coverage. The agent must infer its meaning from the name alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return', the resource 'topic overview markdown', and the condition 'if present', which effectively distinguishes it from sibling tools like 'write_topic_overview'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. The purpose is clear but no context is provided for decision-making in a complex toolset.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explains auto-routing behavior and mentions the dry_run parameter, but does not describe side effects, authorization needs, or potential destructiveness. The information is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence front-loads the core purpose ('Unified ingest') and efficiently details the routing logic with examples. No unnecessary words or repetitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters with no documentation and the complexity of an ingest operation, the description is insufficient. It does not cover how to use each parameter, expected output, or error cases. Although an output schema exists, the description lacks completeness for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so parameter descriptions are missing entirely. The description only indirectly clarifies the 'source' parameter by listing example source types (DOI, arXiv, folder, URL). Other parameters like skip_verify, no_zotero, dry_run are not explained, adding minimal value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a unified ingest tool that auto-routes based on source shape, and it distinguishes between siblings by naming specific delegated actions (add_paper, import_folder, URL file). The verb 'collect' is implicit in 'ingest'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (for DOI, arXiv, folder, URL inputs) and references alternative tools for specific use cases. However, it does not explicitly state when not to use it or provide exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It describes the tool as performing general web search and lists content types, but doesn't disclose specifics like search engine used, rate limits, or how results are returned. However, typical web search behavior is predictable, and the output schema covers return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, each serving a distinct purpose—what it does and when to use it. No superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to explain critical parameters like 'provider' and 'max_results'. For a web search tool, these are important for proper use. The description is incomplete for a task this complex.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description adds no information about parameters. Users are left to infer meanings of 'query', 'max_results', and 'provider' from their names alone. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool performs general web search and lists specific content types (blog posts, docs, news, GitHub READMEs). It distinguishes itself from the sibling tool auto_research_topic by noting it covers non-peer-reviewed sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: alongside auto_research_topic when the user needs content beyond peer-reviewed papers. This directly addresses tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It explains the dual mode of operation (list vs. apply) and the 'everything' shortcut. It also mentions the return format. The description implies destructive capability with 'apply=True to actually remove,' which is sufficient transparency. No hidden behaviors are apparent, though it could explicitly warn about irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (5 lines), with clear sections: purpose, usage guidance, and return format. Every sentence adds value with no redundancy or fluff. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters and no annotations, but does have an output schema. The description covers the overall purpose, common usage patterns, and return format. However, it misses details on several parameters (e.g., retention settings) and does not explain how they interact. This could lead to suboptimal use by an AI agent, but the main functionality is clear enough for basic tasks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains the 'everything' and 'apply' parameters and mentions the categories (bundles, debug logs, artifacts). However, it does not explain parameters like 'keep_bundles', 'debug_older_than_days', 'keep_artifacts', or the other booleans. Only partial coverage is provided, which is minimally adequate but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: garbage-collecting accumulated research-hub files, with a specific verb ('Garbage-collect') and resource. It also explains the default behavior (listing candidates) and the version requirement. However, it does not differentiate from sibling tools like 'tidy_vault', which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage triggers: 'Use when: user says "clean up", "free disk space", or "GC the vault".' It also explains the difference between default (dry-run) and apply mode, giving clear guidance on when to pass parameters. However, it does not mention scenarios where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: slugification/reuse of cluster_slug, multi-source search, ingestion pipeline, conditional crystal generation with LLM CLI requirement, and return value structure. However, it doesn't mention potential side effects like creating new clusters or modifying existing ones beyond reuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is compact yet comprehensive. Front-loaded with the core pipeline, each sentence adds distinct value: purpose, slug logic, actions, crystal condition, usage cue, and return format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters and no annotations, the description covers the main workflow and return values but omits explanations for most parameters. It provides a good high-level overview but lacks depth for configuration options, making it only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. Only topic, cluster_slug, and do_crystals are briefly explained. The other 11 parameters (max_papers, field, dry_run, etc.) are not described, leaving the agent without guidance on their purpose or effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool as a 'one-shot research pipeline' specifying actions: search, ingest, NotebookLM brief, and optional crystals. It differentiates from sibling tools by combining multiple steps, with explicit mention of searching arXiv + Semantic Scholar, ingesting into Zotero + Obsidian, and generating a NotebookLM brief.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when: user says "research X for me" or "find papers on X".' This gives clear context for usage, though it does not provide exclusions or alternatives for when a simpler tool would suffice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that each sub-step is non-fatal and failures are logged without aborting. However, it does not clarify whether the tool is read-only or modifies the vault by default, nor does it explain the effect of the 'apply_cleanup' parameter on the behavior beyond the preview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core action, followed by key behavioral notes and usage triggers. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, when to use, and return format adequately. Lacks prerequisites or side effects, but given the output schema exists to detail return values, the description is reasonably complete for a multi-step maintenance tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds some meaning by mentioning 'cleanup preview' in the return, but it does not explain how the 'apply_cleanup' parameter affects the tool's behavior. The parameter's role (apply vs preview) is only implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'one-shot vault maintenance' and lists specific sub-steps: doctor autofix, dedup rebuild, bases refresh, and cleanup preview. This distinguishes it from sibling tools like 'run_doctor' or 'cleanup_garbage', which handle individual steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: when user says 'tidy', 'maintenance', or 'vault health check'. Does not explicitly list when not to use or alternative tools for single steps, but the context implied by listing sub-steps provides adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the tool as a single entrypoint and mentions the deprecated aliases, but does not explicitly state the potential destructive nature of the 'apply' action when 'dry_run' is false. More explicit warnings about side effects 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, front-loading the core purpose. While it is moderately lengthy, each sentence adds value by explaining actions, usage guidance, and deprecation details. It is concise relative to the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, 0 required, 100% schema coverage, and an output schema), the description covers workflow, usage guidance, parameter context, and deprecation details. It is complete enough for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter thoroughly. The description adds context about the overall workflow and action selection, but does not significantly enhance understanding of individual parameter meanings beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs the cluster-rebind workflow specified by an action, consolidating four legacy operations. It lists specific use cases and distinguishes from siblings like 'prune_cluster' and CLI delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'When to use' and 'When NOT to use' sections, providing concrete scenarios and naming alternative tools (e.g., 'research-hub clusters delete', 'prune_cluster'). This provides clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides basic transparency: it emits a prompt. However, it does not disclose whether the tool has side effects, what the prompt contains, or if it is purely read-only. The behavior is implied but not fully detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no filler. The first sentence states the core purpose, the second provides essential context about the multi-phase flow. Every sentence adds unique value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the 100% schema coverage and the presence of an output schema, fully specifies the tool. It covers the tool's role in the workflow and the inputs needed. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with parameter descriptions. The description adds no extra semantic detail beyond noting the phase; the schema already explains 'cluster_slug' and 'subtopics' structure. Baseline 3 applies as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: building the Phase 2 LLM prompt for sub-topic assignment. It specifies the verb ('emit') and resource ('the prompt'), and distinguishes from sibling tools like 'propose_subtopics' (Phase 1) and 'apply_subtopic_assignments' (Phase 3) by referencing the multi-phase flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's role in the multi-phase topic build flow, indicating it should be used after 'propose_subtopics' and before 'apply_subtopic_assignments'. It lacks explicit when-not or alternative usage, but the flow context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It details the process (opens notebook, extracts briefing, saves to specific path, updates cache). However, it omits error handling or prerequisites like having a saved session.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (4 sentences) and front-loaded with the main action. Every sentence adds necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not explain return values. It covers the process, file naming, and cache update. Minor gap: no mention of prerequisites like having a local session or existing briefing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are described in the schema (100% coverage). The description adds value by explaining the artifact_type limitation ('only brief in v0.9.0') and headless use case (MCP server without display), going beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action (download), resource (NotebookLM briefing), and destination (vault). It uses a specific verb and resource, distinguishing it from siblings like notebooklm_generate or notebooklm_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (generated briefing, local session) but lacks explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or exclusions, relying on the sibling list for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details three internal routing paths, prerequisites (NotebookLM login), and parameter-specific behaviors (e.g., question=None for briefing modes, force_regenerate). Could mention error scenarios or rate limits, but overall strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bullet points, though somewhat lengthy. Every sentence adds value; however, the deprecated aliases list could be more concise. Still, it is organized and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no annotations, and presence of output schema, the description is highly complete. It covers all four modes, routing logic, and when to use alternatives, leaving little ambiguity for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description adds value by explaining parameter interdependencies (e.g., mode interaction with source, question None for certain modes) and prerequisites, but the schema already describes each parameter well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it answers a question about one cluster, dispatching to internal sources. It specifies the resource (one cluster) and action (question answering), and distinguishes from siblings like read_crystal (by slug) and search_papers (multi-cluster).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' and 'When NOT to use' sections, referencing specific sibling tools (read_crystal, web_search, search_papers, read_cluster_memory) and giving clear guidance on source/mode selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the return keys and that it inspects JSON, but does not detail side effects, error handling, or whether it is read-only. Adequate but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet structured with clear sections: action, usage, args, returns, example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description covers purpose, parameters, return keys, and an example. It lacks error behavior details, but overall is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning by providing examples (cs_swe, bio_protein) and explaining that name is a bundled example id, which compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a bundled example cluster definition and mentions inspecting sample JSON before examples_copy, distinguishing itself from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (before copying an example) and when not to use (to list names, use examples_list instead), providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It describes the tool as parsing and auditing, implying a read-only analysis, but does not explicitly state side effects, permissions, or whether it modifies state. The return example and keys provide some insight, but more explicit behavioral context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with distinct sections: purpose, usage, params, returns, example. It is concise with no wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers the return keys and provides an example. It distinguishes from relevant siblings (fit_check_drift, fit_check_emit). It is slightly lacking in prerequisites or edge cases, but overall sufficient for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description compensates by explaining the single parameter: 'cluster_slug: cluster whose briefing is audited.' This adds meaning beyond the schema, which only provides the name. An example usage further clarifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Parse the latest NotebookLM briefing for off-topic flags.' It uses a specific verb 'parse' and a resource 'NotebookLM briefing', and distinguishes itself from sibling 'fit_check_drift' by noting it audits before drift check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'When to use: after NotebookLM flags papers. When NOT to use: to emit scoring prompts; use `fit_check_emit` instead.' This clearly indicates when to use this tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It explains that the tool emits a JSON prompt and describes the return structure, but does not discuss side effects, safety, or idempotency. While likely non-destructive, more explicit behavioral context could improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: it begins with the core purpose, followed by usage guidelines, arguments, return values, and an example. Every sentence is concise and adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema is present, the description effectively covers the return structure (prompt, paper_count, error) and provides an example. With only one simple parameter, the description is complete and sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the parameter 'cluster_slug' as the cluster whose notes are scanned for TODO placeholders. This adds meaningful context beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Build an autofill prompt') and the resource ('paper notes with TODO bodies'). It also explicitly distinguishes the tool from its sibling 'autofill_apply' by noting when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions for use ('after ingest creates notes with abstracts but TODO content') and non-use ('to write AI output; use autofill_apply instead'). This gives clear guidance on when the tool is appropriate and when to choose an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it generates a file and returns path, plus what the dashboard contains. Without annotations, it covers key behaviors, though it could mention any prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences front-loading purpose, return value, and usage. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with output schema, description sufficiently explains what it does, what it returns, and how to use the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description cannot add param meaning. Baseline is 4; description adds value by explaining output and content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it generates a personal HTML dashboard for the vault, with specific verb and resource. Distinct from siblings as only dashboard tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use: to see cluster overview, paper counts, etc. Provides clear context but lacks explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully details the output structure including fields like intent_summary, suggested_topic, clarifying_questions, next_call, and estimated_duration_sec. No mention of side effects, but tool appears non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and examples. Front-loaded main purpose. Slightly verbose but all content relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers input, output fields (though not formal schema), and usage flow. Does not detail error handling or edge cases, but adequate for a planning tool with one parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'user_intent' with no schema description. Description adds value by explaining expected input as freeform intent and providing examples, compensating for schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'convert' and resource 'freeform user intent into a structured research plan'. Explicitly distinguishes from sibling auto_research_topic by stating order of use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (vague, ambitious, potential cluster collisions) and gives example user statements. Clearly states to call before auto_research_topic and specifies confirmation flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses that the tool does not create anything, only proposes names. While it does not detail the response format, the existence of an output schema and the mention of 'showing suggestions' sufficiently conveys non-destructive read-like behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and provides workflow instructions without any wasted words. Extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (single required parameter, full schema coverage, output schema exists) and the rich context of sibling creation tools, the description fully explains the tool's role in the workflow, making it complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described in the schema. The description does not add further meaning to the 'topic' parameter beyond what the schema already provides, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('propose names') and the resource ('new research collection'), and distinguishes itself from creation tools by emphasizing 'without creating anything'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to use this BEFORE creating clusters/collections/notebooks, to show suggestions to the user, and to proceed with create tools only after user confirmation. Provides clear workflow and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it invokes an LLM CLI (claude, codex, gemini with override), can write to Obsidian and Zotero when apply=True, returns JSON by default, and saves a prompt file if CLI is missing. The return structure is also described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded purpose statement, followed by mode details, usage cues, and fallback instructions. It is concise but could trim some procedural repetition (e.g., re-explaining the apply flow).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main workflow, fallback, and return format, but does not explain the individual write flags or any prerequisites like how to obtain a cluster_slug. Given the tool's complexity and lack of schema descriptions, it is largely complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'cluster_slug' and 'llm_cli' verbally, and mentions 'apply' behavior, but does not describe the boolean parameters 'write_zotero' and 'write_obsidian', leaving their purpose unclear. Partial coverage across 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear action: 'Generate per-paper Key Findings + Methodology + Relevance via LLM CLI.' It specifies the resource ('cluster_slug') and distinguishes from sibling tools like 'apply_cluster_summaries' and 'ask_cluster' by detailing the generation process and output modes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: when user says 'summarize this cluster's papers', 'fill the TODO Findings', or after 'auto' ingest. It also provides an alternative path: if no LLM CLI is available, the prompt is saved and can be processed with 'apply_cluster_summaries' or the CLI re-run.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It describes that the tool updates notes and consumes autofill_emit JSON, and lists return fields with an example. However, it does not detail the extent of updates (e.g., overwrite/append) or side effects, leaving some ambiguity. Still, it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with minimal fluff: a one-sentence purpose, usage guidelines, parameter explanations, return fields, and an example. It is front-loaded and each sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 params, no output schema provided) the description covers the main use case, lists return fields, and gives an example. However, the example is somewhat ambiguous (empty filled list) and does not clarify behavior for different 'scored' formats. Still, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description manually explains each parameter: 'cluster_slug: cluster to update; scored: list or {"papers": [...]}'. This adds meaning beyond the raw type definitions, compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb 'Apply' and resource 'AI-authored autofill sections to paper notes'. It clearly distinguishes from sibling 'autofill_emit' by stating it consumes its JSON output, ensuring the agent uses the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('after an AI returns summaries for an autofill prompt') and when NOT to use ('to generate prompts; use autofill_emit instead'), including the name of the alternative. This provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers the key behavioral aspects: input processing (scored list), threshold filtering, auto-threshold heuristic, and output writing. It does not explicitly mention whether it overwrites existing files or the stash, which would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, detailed process, and usage guidelines. It uses formatting for code and clear sections. While slightly verbose, it remains focused and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity and presence of an output schema, the description adequately covers prerequisites, input handling, filtering logic, and integration with the discovery flow. It addresses edge cases like missing scores and auto-threshold, making it complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining default threshold behavior (falls back to cluster default), that missing scores are treated as 0, and that 'scored' can be a list or dict. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Apply fit-check scores from an AI judge and produce a papers_input.json ready for ingest.' It specifies the tool is the second half of the discovery flow, distinguishing it from siblings like discover_new or discover_clean.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'When NOT to use' sections provide clear guidance, including prerequisites (run discover_new first) and alternatives (add_paper, fit_check_apply). This helps the agent select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return format (keys prompt, target_count, error) and provides an example, but could elaborate more on side effects or safety. However, given no annotations, the description sufficiently discloses behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise with clear sections (description, when to use, args, returns, example) and front-loaded purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides sufficient information for a simple tool: purpose, usage conditions, parameter semantics, and return format. Lacks output schema details but example compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaningful context to parameters beyond the input schema: cluster_slug as context, query as seed, count as target count. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it emits query-variation prompts for discovery search and distinguishes itself from sibling tool discover_new by specifying that discover_new should be used to actually run search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (before discovery with narrow seed query) and when not to use (to run search; use discover_new instead), offering 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, the description discloses key behavior: it persists decisions before pruning and returns status keys. The example adds clarity. Lacks discussion of permissions or side effects, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a one-sentence summary, usage guidance, args, returns, and an example. Every part adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no nested objects, output schema available), the description covers purpose, usage, parameter meaning, return format, and an example. It is fully sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one parameter and 0% schema coverage, the description adds value by explaining that cluster_slug refers to the cluster whose sidecars and notes are used. This goes beyond the parameter name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: converting fit-check sidecar decisions into paper labels and persisting them. It distinguishes itself from siblings like fit_check_apply and fit_check_audit by the specific operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use ('after accepted and rejected sidecars are written') and when not to use ('to score candidates; use fit_check_apply instead'), offering clear context and an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it re-scores papers after audit, implying mutation. With no annotations, this is valuable. Lacks specifics on side effects beyond scores (e.g., state changes) but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: two lines of purpose, usage rules, parameter descriptions, return keys, and example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, parameters, returns, and context (after audit). With output schema existing, return info is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds clear meaning: cluster_slug described as 'cluster', threshold as 'accepted score cutoff' with default. Example reinforces usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb (emit) and resource (drift-check prompt) and context (after fit_check_audit). Differentiates from sibling fit_check_apply by indicating when NOT to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' and 'When NOT to use' sections with a clear alternative (fit_check_apply).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavioral traits: defaults for archive, delete, dry_run; two-step workflow; audit trail reversibility. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with bullet points for usage guidelines. Every sentence adds value, no fluff. Appropriate length for complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and output schema exists, description is complete: covers purpose, usage, parameter behavior, sibling relationships, and workflow. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value beyond schema by explaining parameter interactions (delete has no effect when archive=True), defaults, and expected label values. Not quite 5 because schema already does heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Archive or delete paper notes in a cluster whose frontmatter carries label', specifying resource and condition. It distinguishes from siblings by naming related tools (apply_fit_check_to_labels, cluster_rebind).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' (after apply_fit_check_to_labels) and 'When NOT to use' (adding labels, deleting entire cluster, rebinding orphans), with named alternatives (apply_fit_check_to_labels, CLI, cluster_rebind).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

[![research-hub MCP server](https://glama.ai/mcp/servers/WenyuChiou/research-hub/badges/card.svg)](https://glama.ai/mcp/servers/WenyuChiou/research-hub)

Score Badge

Copy to your README.md:

[![research-hub MCP server](https://glama.ai/mcp/servers/WenyuChiou/research-hub/badges/score.svg)](https://glama.ai/mcp/servers/WenyuChiou/research-hub)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/WenyuChiou/research-hub'

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