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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.