Scholar Feed

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

Annotations already mark readOnlyHint=false, and the description adds substantial behavior: MUTATES and auto-saves to the library, idempotence via no-op on duplicates, get-or-create side effect, and the SF_API_KEY requirement. No contradiction with annotations.

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

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

The description is compact and front-loaded: the first sentence states the action and addressing options, and the remaining sentences each add a distinct behavioral or auth detail. No filler or 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?

Covers the core action, addressing alternatives, get-or-create semantics, nesting, side-effect auto-save, idempotence, and authentication. With an output schema present and annotations covering the safety profile, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that collection_name needs no pre-lookup and that '/' nesting files the paper under a folder, going beyond the schema's existing 'Created if it doesn't exist' and 'Use / to nest' notes.

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

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

States a specific verb and resource: 'Add a paper to a collection' with two addressing modes (collection_id or collection_name). It also distinguishes itself from siblings by noting get-or-create by name and auto-saving to the library, which separates it from create_collection and save_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?

Gives clear invocation guidance: use collection_id OR collection_name, and no need to look up an id first because names are get-or-create. It does not explicitly name sibling alternatives or exclusions, but the context is strong enough that an agent can decide when to call it.

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

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

Despite annotations already stating readOnlyHint=false and destructiveHint=false, the description adds material behavioral context: the upsert semantics ('writing again replaces it'), repeated-call safety, deliberate lack of delete, the SF_API_KEY requirement, and the get action that returns without modifying. These details go well beyond the structured 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 long but tightly organized with clear section markers (WHY IT MATTERS, WRITE A JUDGMENT) and every sentence adds operational or strategic value. The core purpose is front-loaded in the first sentence, and no content is redundant with the input schema or annotations.

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

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

For a tool that is conceptually simple but operationally nuanced, the description covers everything an agent needs: what to write, why it matters, when to use get, how to correct, auth requirements, and the relationship to list_library. The output schema exists, so return-value detail is not needed, and the guidance is complete enough to invoke correctly in a wide range of session contexts.

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%, so the baseline is 3, but the description adds significant parameter-level context: it explains when action='get' should be used, that note_text is ignored for get, and that overwriting is the correction mechanism. It does not repeat schema types but clarifies intent and interplay between parameters.

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 opens with a specific verb and resource: 'Record YOUR verdict on a paper' and immediately clarifies the scope ('why it matters for your work, when to use it, or why you ruled it out'). It also contrasts itself with the paper's existing llm_summary and abstract, which clearly separates it from sibling tools like fetch_fulltext or get_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?

The description provides explicit when-to-use guidance, including the cross-session persistence rationale and the fact that list_library surfaces note_text on every saved paper. It explicitly tells the agent what not to do ('WRITE A JUDGMENT, NOT A SUMMARY') and when to read first via action='get', making the call decision unambiguous.

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?

Annotations already mark it read-only, but the description goes further by disclosing that it requires SF_API_KEY, that it reads the saved set, that it produces inline [arXiv-ID] citations, and that quotas differ by account tier. This adds meaningful behavioral context beyond the 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 compact and efficient: it front-loads the core purpose, then adds contrast, scoping options, read-only status, auth requirement, and quota. Every sentence contributes meaningful information 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 and annotations, the description covers all essential context: what the tool does, how it differs from a sibling, how scoping works, auth requirements, and usage limits. Nothing critical is missing 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?

Schema coverage is 100%, so the schema already documents each parameter. The description adds valuable relational semantics by saying collection_name OR collection_id can be used and that omitting both uses the whole library, which is not fully captured by the schema alone.

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

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

The description clearly states a specific verb ('Answer a question') and resource ('the papers you've saved'), and explicitly contrasts itself with find_gaps. This makes its purpose unmistakable and differentiates it from a close sibling.

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

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

It explicitly names the inverse tool (find_gaps) and explains the distinction: ask_library reasons over what you have, while find_gaps finds what you're missing. It also clarifies optional collection scoping and the default whole-library behavior, giving clear guidance on when and how 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?

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds substantial behavioral detail beyond that. It discloses that there is no LLM call at query time, that matching is case- and spacing-insensitive, that evidence is drawn only from arXiv benchmark tables, that production frameworks never appear as winners, and that the grounding gate checks only receipt authenticity, not attribution accuracy. It even warns that no precision number has been measured and advises citing the source rather than asserting supersession as fact. That is unusually transparent about limitations and is not contradicted by any annotation.

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 long but every paragraph earns its place: the first paragraph defines the tool's question and answer shape, the second covers when to use it and the coverage caveat, and the third explains trust boundaries. It front-loads the most important information. A small deduction because the grounding/attribution paragraph is dense and could be tightened, and the phrasing 'GROUNDING — how far to trust an individual receipt' repeats a caveat that could be absorbed into the previous paragraph. It is still well structured and not padded.

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 complex read-only research tool with no required parameters and a rich output schema, the description covers everything an agent needs: query modes, inputs, output items, limitations, trust model, and source coverage. The output schema exists and is structured, so the description is not responsible for enumerating return fields. The only minor omission is that the description doesn't mention pagination or default behavior for limit, but that is documented in the schema. Overall this is one of the more complete and decision-ready tool descriptions an agent could encounter.

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 baseline is 3, but the description adds meaning beyond the property descriptions. It explains that omitting method yields a whole-family map, that omitting family (or passing 'list') yields the live family list, and it illustrates valid values ('rag', 'peft', 'kvcache', 'SnapKV', 'LoRA'). It also clarifies the matching behavior and the role of limit. The one gap is that the description doesn't explicitly define what a 'family' is beyond examples and doesn't enumerate all families, but the schema plus description is sufficient for confident 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 opens by stating exactly what question the tool answers: 'for my problem, is the method I use superseded — and by what?' and attaches that to a concrete knowledge base. It names the input types (family and method) and the output (a verdict, critiques, benchmark edges, alternatives), and is clearly distinguishable from siblings like find_gaps or ask_library. It covers both single-method and whole-family query modes, which is a level of specificity beyond a generic verb+resource statement.

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 says explicitly when to use this tool: when choosing or reviewing a technique, when checking whether a baseline has been beaten, and when exploring a family via the whole-family map. It also gives a strong 'when-not' signal: it is a literature signal, not a deployment recommendation, so the agent knows not to treat it as a definitive endorsement. The did-you-mean behavior and family='list' route are also spelled out, so an agent knows what to do when uncertain about inputs.

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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses idempotency, that no watermark is advanced, that only digest delivery advances it, and that there is no mark-on-read. It also states the required SF_API_KEY. These are meaningful behavioral details that the annotations do not provide.

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

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

Four sentences, each earning its place: the action, the scoping rule, the read-only idempotent behavior, the use case, and the auth requirement. The most decision-relevant information is 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?

With an output schema present, the description covers return shape via the search_papers reference. It covers side effects, scoping, authentication, and use case. For a tool with three optional parameters and a read-only safety profile, nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a concise prose explanation of the OR relationship between watch_name and watch_id and the default 'all watches' behavior, but it does not substantially go beyond what the schema already states.

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 opens with a specific verb ('Pull'), a clear resource ('new matching papers since the last digest delivery'), and the same shape as search_papers results. It also distinguishes scoping modes and contrasts with the digest-delivery mechanism. This makes the tool's purpose immediately distinct from siblings like list_watches, preview_watch, and 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?

The description gives clear context for when to use the tool: the in-session 'anything new on my watches?' pull, scoped optionally by watch_name or watch_id, or all watches when both are omitted. It does not explicitly name alternatives or state when-not-to-use conditions, but the intended usage is unambiguous.

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?

Beyond the readOnlyHint annotation, the description discloses specific behavior: results are capped at 500 edges, sorted by papers_count DESC, and computed within the window_years window. It also clarifies edge direction semantics ('from' is an input author, 'to' is a co-author). These are valuable operational details not in the annotation.

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 about 80 words and front-loads the core purpose, then adds the output shape, use cases, and key limits. No filler or 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?

The tool is a read-only query with 100% parameter documentation and an output schema. The description adds the cap, ordering, default window, and use cases, leaving no critical behavior uncovered.

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 baseline is 3. The description links author_ids to the 'from' output field and window_years to the 'within the window' constraint, but those semantics are largely inferable from the schema. No substantial parameter nuance is added.

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

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

The first sentence names a specific verb and resource: 'Find the co-authorship neighborhood of one or more authors.' It goes on to define the exact edge structure, and no sibling tool covers co-authorship graphs, so it is easy to distinguish.

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 lists three explicit use cases: AC reviewer triage, researcher disambiguation, and expanding seed authors into a community. It also points to find_author as the source for author IDs in the schema, giving a prerequisite. It doesn't explicitly mention when not to use the tool, but the use-case list is clear 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral context: the operation is a mutation, duplicates are idempotent (get-or-create, never errors), folder hierarchy is derived from the name, and SF_API_KEY is required. This goes well beyond the structured fields.

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 compact and front-loaded: it opens with the primary purpose and mutation warning, then covers duplicate behavior, nesting syntax, and authentication in three purposeful sentences. Every sentence adds needed information with no filler.

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

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

Given a single required parameter, complete schema coverage, an output schema, and clear annotations, the description covers everything an agent needs: mutation semantics, duplicate handling, folder derivation, and auth. There are no material gaps 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 coverage is 100% for the single 'name' parameter, so the schema already documents the parameter. The description adds value by clarifying the nesting semantics ('/' creates a folder path) and that the folder is derived entirely from the name, plus the duplicate behavior. This exceeds the baseline for high schema 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 states a specific action ('Create') on a specific resource ('a new named collection') and immediately flags that it mutates state. It also distinguishes itself from read-only siblings by noting the get-or-create behavior, so an agent can tell it apart from list_collections or add_to_collection.

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 gives clear, actionable context: create a collection by name, duplicates return the existing collection, and '/' nesting means no parent must be created first. It does not explicitly name alternative tools for when not to use it, but the behavior guidance is specific enough for an agent to make the right call.

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 clearly states MUTATES, get-or-create semantics, duplicate handling ('never errors on duplicate'), criteria precedence, default ranking behavior, and the requirement for SF_API_KEY. Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds meaningful behavioral context. Minor gap: it doesn't describe what the response contains, but an output schema exists.

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

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

The description is dense but organized: it front-loads the core purpose and mutation warning, then explains get-or-create, then the two forms and their trade-offs. Every sentence carries meaningful guidance. It is long because the tool has two forms and many parameters, but it earns its length; a small amount of redundancy (e.g. repeating that criteria is recommended) exists.

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 an 11-parameter tool with nested objects, a full output schema, and many siblings, the description provides comprehensive context: how to choose between forms, what the default ranking is, how to tighten it, get-or-create semantics, auth requirements, and how it relates to preview_watch/update_watch/check_watches. No critical operational guidance is missing.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds valuable semantic guidance beyond the schema: explaining which fields are AND-composed, that criteria takes precedence over legacy seeds, the 'rising' default rationale, and the anti-noise min_impact_pct usage. Some structured sub-fields (e.g. collections.relation) are more detailed in the schema than the description, but the description adds enough to justify above-baseline.

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 ('Create'), a resource ('standing watch'), and its core behavior (evaluated daily against newly-indexed papers, surfacing matches via email digest and check_watches). It also distinguishes the v2 structured form from the legacy seed form, clearly separating this from siblings like preview_watch and update_watch.

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

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

The description explicitly says when to use the structured criteria form (recommended, agent-tunable), advises tuning with preview_watch first, points to update_watch for later edits, and notes the get-or-create duplicate behavior. It also explains when the legacy seed selector applies and that criteria takes precedence, giving clear usage direction.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation fact is not new. The description adds valuable behavioral context beyond the annotations: the operation is idempotent, a missing watch produces no error, and SF_API_KEY is required. These details meaningfully inform an agent's expectations about side effects and failure modes.

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 compact and front-loaded: the core action comes first, followed by the idempotency caveat, the update_watch alternative, and the auth requirement. Every sentence earns its place, with no filler or 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 simple two-parameter delete tool with an output schema and destructive annotations, the description is highly complete. It covers the core action, idempotency, the alternative tool for in-place changes, and auth. The only minor gap is the lack of explicit precedence or conflict behavior when both name and watch_id are provided, but that is a small omission given the schema already marks them as alternatives.

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 documents both params with 100% coverage, so the baseline is 3. The description reinforces the 'watch_id OR name' relationship, which is useful, but it does not add extra semantics such as what happens if both are supplied or whether one takes precedence. The schema descriptions already carry most of the parameter 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?

The description states the exact operation: 'Delete a watch' and identifies how the resource is addressed (by watch_id OR name). It also explicitly distinguishes itself from update_watch, so an agent can tell this delete tool apart from other watch-related siblings without opening schemas.

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 gives clear when-to-use guidance and names the alternative: 'To change a watch in place ... use update_watch instead of delete-and-recreate.' It also clarifies an important edge case: deleting a non-existent watch is a no-op, which prevents the agent from treating missing IDs as errors.

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?

Annotations already mark the operation read-only, and the description adds materially beyond that: Pro-account API-key requirement, 403 pro_required for anonymous/free callers, approximate cost per call, and 30/minute rate limit. It also clarifies that task_type changes which side (corpus/query) the embedding aligns with.

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

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

The description is front-loaded with the core purpose and follows with a numbered workflow, task-type guidance, and operational constraints. Every sentence carries distinct information about how, when, or under what conditions to call the tool.

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

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

The output schema exists, so the return embedding format need not be restated. The description covers the workflow, parameter semantics, auth prerequisites, failure mode, cost, and rate limit, leaving no practical gap 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 coverage is 100%, so the baseline is 3; the description then adds value by tying text to the hypothetical-answer step and task_type to embedding side. The schema already documents defaults and enum semantics, so the description's incremental parameter meaning is clear but not exhaustive.

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

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

The description names the exact operation — 'Embed a text string into a 768-dim Gemini Flash vector' — with a specific verb, resource, and dimensional output. It also frames the embedding in the context of HyDE-style retrieval, distinguishing it from sibling tools that operate on papers/collections rather than producing embeddings.

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

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

It gives a concrete three-step HyDE recipe, explains when to use RETRIEVAL_DOCUMENT vs RETRIEVAL_QUERY, and explicitly routes the output to 'search-style tools.' It also states the Pro-only constraint and 403 failure mode, so an agent can select the tool only when credentials qualify.

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 readOnlyHint and destructiveHint already covering safety, the description adds substantial behavioral detail: LaTeX-to-PDF fallback, mode-specific payload sizes, ~95% availability, 404 semantics, and latency. This goes well beyond the annotations and helps the agent anticipate outcomes.

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 dense but every sentence earns its place: behavior, mode comparison, size estimates, availability, and failure semantics. It is front-loaded with the core extraction behavior and uses structure to separate the two modes clearly.

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 two-parameter read-only tool with an output schema, the description covers what the tool does, how the modes differ, what the fallback behavior is, failure meaning, and expected latency. Nothing critical is missing 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the 'sections' parameter, including default behavior, approximate character counts, table captions, and the 'ideal for checking a reported number' use case, which is more than the schema alone provides.

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 extracts paper content from arXiv LaTeX source with PDF fallback, which is specific and actionable. However, it does not explicitly differentiate from sibling tools like get_paper, leaving some inference to the agent.

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 gives explicit mode-selection guidance, telling the agent to prefer 'results' unless the whole paper is needed. It does not address when to choose this tool over sibling alternatives such as get_paper or search_papers, so it is clear but not fully exclusive.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the two-mode branching behavior, how queries are matched (embedding similarity vs fuzzy matching), and the exact return fields for both modes.

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, front-loaded with the key usage rule, and organized into clear Q-MODE and ID-MODE sections. Every sentence contributes either usage guidance or return-value detail, with no filler or 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 read-only, two-mode lookup tool with a full input schema and an output schema, the description covers mode selection, the exactly-one rule, q-mode-only parameters, source of IDs, and detailed return contents for both modes. Nothing essential is missing 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 coverage is 100%, so the schema already documents all four parameters. The description adds important cross-parameter context not fully captured by the schema: the requirement to provide exactly one of q or id, and the association of field and limit with q-mode only. This goes beyond the baseline of 3 for high-coverage schemas.

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 clear, specific purpose with two explicit modes: searching for authors by topic/name and looking up a single author profile by ID. It distinguishes itself from sibling tools like search_papers and co_author_graph by focusing on author identity as the resource and by referencing where IDs come from.

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 gives clear operational guidance: 'Provide exactly one of q or id', explains what each mode does, and identifies q-mode-only parameters. It also tells the agent where to obtain author IDs. However, it does not explicitly state when not to use this tool versus sibling tools, stopping short of a 5.

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?

Beyond the readOnlyHint annotation, it discloses that the tool subtracts the user's saved set, derives the niche from the seed, runs lineage and novelty searches, and requires SF_API_KEY plus Pro access. It also states the free-account upgrade prompt behavior, adding valuable operational 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 compact, front-loads the core value proposition, and every sentence adds either semantics, constraints, or operational context. It avoids repeating schema details and remains easy to scan.

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

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

With an output schema present and the annotations covering safety, the description supplies the remaining context needed to select and invoke the tool correctly: seed exclusivity, bucketing logic, auth/Pro requirement, and behavior. Nothing critical is missing.

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

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

Schema coverage is already 100%, but the description adds the critical 'exactly one seed' constraint and explains what each bucket means, mapping to the scope enum. It reinforces that collection_name is resolved by the backend, which is useful beyond the raw schema.

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

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

The description names a specific verb and resource ('find important work you HAVEN'T saved') and clarifies the output as two gap buckets. This distinctly separates it from sibling search and lineage tools, which query saved or cited work rather than subtracting the user's library.

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

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

The description clearly frames when to use the tool ('a what am I missing? analysis') and specifies the exact-seed rule. It does not explicitly contrast with alternatives like search_papers or get_foundational_lineage, but the context makes the intended use obvious.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful non-obvious behavior: ranking by impact score, the meaning of each direction, and the 12-field versus 28-field response shape, going beyond the schema's field-level details.

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 tightly packed sentences provide the key behavior, direction definitions, and response shape with no filler. The most important information is front-loaded, and each sentence earns its place.

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

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

With a rich output schema, full parameter documentation, and read-only annotations, the description has little left to cover. It successfully adds the sort order, direction semantics, and default output shape, making the tool fully understandable and callable without missing context.

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

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

Schema description coverage is 100%, so the schema itself documents all six parameters. The description reinforces the verbosity and direction semantics but does not need to compensate for undocumented parameters, keeping the score at the baseline.

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

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

The description states a specific verb and resource ('Get the citation graph for a paper') and adds a distinguishing sorting behavior ('sorted by citing-paper rank_score'). It also defines both direction values, making the tool's scope unambiguous and separating it from related graph tools like co_author_graph.

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 explains the two directions ('citing' vs. 'cited_by') and notes the default versus verbose response shape, giving the agent a solid sense of what the tool will do in normal use. It does not explicitly compare against sibling tools or say when not to use it, but the context is clear enough for selection.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds meaningful behavioral context beyond that: it performs no synthesis, makes no LLM calls, and does not require a Pro API key. The ranking weights (0.6 citation count, 0.4 semantic similarity) also disclose exactly how results are scored. This is rich, honest behavioral disclosure.

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

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

The description is concise and front-loaded with the core result, followed by ranking behavior, use cases, the alternative, and cost characteristics. Every sentence earns its place, and there is no fluff or repetition of schema content. The structure makes the tool easy to scan and act on.

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 only two simple parameters, full schema descriptions, an output schema, and read-only annotations, the description is complete. It covers what the tool returns, how results are ranked, when to use it, when to use the alternative, and its cost/API-key implications. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the input schema, including defaults, ranges, and examples. The description adds context around ranking behavior but does not need to repeat parameter syntax. Baseline 3 is appropriate because the schema carries the parameter-semantics burden and the description adds modest value.

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

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

The description states a specific verb and resource: 'Returns CANDIDATE FOUNDATIONAL PAPERS for a research topic.' It clearly distinguishes itself as 'cheap retrieval only, no synthesis,' setting it apart from synthesis-oriented tools and the /field-guide skill. The ranking formula further clarifies exactly what the tool produces.

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

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

The description explicitly says when to use it: 'to bootstrap a literature survey or get a fast sense of the landscape.' It also names the alternative: 'For a synthesized orientation report... use the /field-guide skill,' and notes that the skill calls this tool internally. This gives clear routing guidance between the tool and the more comprehensive option.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context: the tool ranks outputs into three tiers, grounds each paper with cited_by_in_niche evidence, collapses universal landmarks into the discipline tier, and surfaces niche-specific anchors that semantic search misses. It also discloses that no LLM calls are required, which is useful operational context beyond the 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 front-loaded with the core purpose, then progresses through output tiers, evidence quality, usage, sibling comparison, and access requirements. Despite covering a nuanced tool, every sentence earns its place and there is no repetitive or filler content. It is dense but well organized.

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 fully covers what the tool does, how the output is structured, how to interpret the tiers, how to choose scope, and how it relates to a sibling tool. An output schema exists, so the detailed return shape does not need to be restated. For a complex niche-mapping tool, the description is complete enough for an agent to select and invoke it correctly.

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

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

All four parameters are already fully described in the schema (100% coverage), including defaults, ranges, enums, and behavioral effects like generality_ceiling demoting landmarks. The description reinforces the tiering concepts but does not add much parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate here.

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 opens with a specific verb and resource: 'Returns the FOUNDATIONAL WORK FOR A PAPER'S NICHE via the citation graph.' It precisely distinguishes this from global citation landmarks and explicitly contrasts itself with the sibling tool get_field_orientation. An agent can immediately tell what this tool does and how it differs from nearby 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?

The description gives direct usage guidance: 'Use this to trace prior art / lineage for a paper, or to find the canonical methods a niche is built on.' It also names the relevant sibling, get_field_orientation, and explains the difference ('topic-anchored and retrieval-only'). It even notes operational constraints ('No Pro key and no LLM calls required'), so an agent knows when this is a cheap, safe option.

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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses important behavioral details: bibtex is single-paper only and requires repeated calls for multiple papers, impact_pct is a cohort-relative percentile computed within an arXiv-category cohort and is NULL for older papers, and verbose mode returns structured extraction fields. This gives the agent a realistic model of the tool's behavior without needing a call.

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 information-dense and every clause adds useful guidance, but it is structured as one long run-on sentence with many semicolons. It is appropriately sized for the tool's complexity, but breaking it into shorter, structured sentences would improve readability and machine parsing. Front-loading the core purpose is done well.

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

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

For a tool with multiple modes (json/bibtex, lean/verbose, batch/single, field selection) and rich output, the description covers all major usage paths. It explains batch limits, format constraints, default vs verbose fields, field subsetting, full-text access, and the special semantics of impact_pct. The presence of an output schema relieves it from documenting every return field, so the description is complete for an agent deciding how to call 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?

The input schema already covers all four parameters at 100%, so the baseline is 3. The description adds significant value by enumerating the default 13-field shape, explaining what verbose=true adds, giving field-selection examples, and describing batch limits. However, there is an inconsistency: the description says 'lean 13-field shape' while the input schema says 'lean 12-field default,' which could confuse an agent trying to reason about the actual response shape.

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 opens with a specific verb and resource: 'Get full details for one or more papers by arXiv ID.' It clearly distinguishes this tool from siblings like fetch_fulltext by later noting that fetch_fulltext is used for full paper text, while get_paper returns structured metadata and summaries.

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 gives clear guidance for batch vs single-paper use, bibtex vs json, lean vs verbose output, and field selection. It also hints at an alternative (fetch_fulltext) for full paper content, though it does not explicitly state when to prefer search_papers or get_citations. The guidance is strong but not fully exhaustive regarding all sibling 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?

Despite annotations only showing readOnlyHint=false and destructiveHint=false, the description discloses meaningful behavior: INSERT-only, idempotent, never un-likes, and requires SF_API_KEY. This goes beyond the annotations and gives the agent a clear model of side effects.

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

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

Three tight sentences deliver purpose, behavior, sibling distinction, and authentication requirement with no filler. The most important functional trait is front-loaded, and every sentence contributes useful, non-redundant information.

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

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

For a single-parameter mutation tool with an output schema and annotations present, the description covers everything an agent needs: what it does, how it behaves, how it differs from save_paper, and the API key requirement. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents arxiv_id as 'arXiv ID of the paper to like.' The description adds no new parameter-level detail, but none is needed given the single self-explanatory parameter; baseline 3 is appropriate.

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 opens with 'Like a paper' and explains the purpose: a 'more like this' calibration signal that tunes the For You feed. It explicitly distinguishes itself from save_paper, so an agent can immediately tell what this tool does and what it does not do.

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?

States when to use this tool versus save_paper: 'like expresses taste for ranking; save bookmarks for later reading.' It also explains key constraints—INSERT-only and idempotent—so the agent knows calling it repeatedly is safe and will not un-like.

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 annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' mostly reinforces the annotation. It adds behavioral context beyond the annotation by specifying authentication requirements ('Requires SF_API_KEY') and scoping behavior to the authenticated user's own collections, which is genuinely useful for invocation.

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

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

The description is three short sentences with no filler. The primary purpose is front-loaded, followed by behavior, a practical usage hint, and a required precondition. Every sentence contributes meaningful 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?

For a read-only, zero-parameter tool with an output schema, the description is fully adequate. It states the scope, the credentialed access requirement, and the intended preceding use case. The output schema covers return-value details, so nothing critical is missing.

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

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

The tool has zero parameters and schema coverage is 100%, so the description has no parameter semantics burden. It does usefully indicate that the output includes paper counts, but this is return-value information rather than parameter guidance. Baseline 4 for a zero-parameter tool is appropriate.

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 names the action ('List'), the resource ('the authenticated user's collections'), and adds specific scope and output details ('named groups of saved papers' with 'paper counts'). This is distinguishable from sibling tools like list_library and add_to_collection because it targets collection entities rather than papers or mutations.

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 this tool: 'Use before add_to_collection to see existing collections.' It also notes the required SF_API_KEY condition. However, it doesn't mention exclusions or when not to use it, such as when the goal is to browse papers rather than collections.

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 though annotations already declare readOnlyHint=true and destructiveHint=false, the description goes far beyond them. It discloses the lean response shape (llm_summary instead of abstract, empty fields omitted), the knowledge-base fields (note_text, is_read, collections), and behavioral instructions like 'READ note_text FIRST' to reuse prior verdicts. Also it exposes token cost implications of verbose mode. This is rich, non-redundant 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 longer than average, but every sentence earns its place. It is front-loaded with purpose and usage, then structured into SHAPE and parameter guidance. The formatting with capitalization and line breaks makes it scannable for an agent, and there is no filler or repetition of schema defaults.

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 read-only listing tool, this description is complete: it states the auth requirement (SF_API_KEY), explains the default versus verbose response shape, describes the state fields that matter for downstream decisions, and provides actionable guidance for the agent. The output schema also exists, so return-value documentation is structurally covered. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context beyond the schema: it explains that verbose is ~4x more token-expensive, that the default lean shape is the right choice for surveying, and that fields overrides verbose while state fields are always included. It does not add new semantics for page/limit, but the existing schema descriptions are sufficient, and the added guidance improves parameter selection.

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 opens with a specific verb and resource: 'List the authenticated user's saved papers (their library), newest first.' This unambiguously distinguishes it from sibling tools like search_papers (search), get_paper (single retrieval), and save_paper (writing). It also states the ordering, making the tool's scope immediately clear.

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 the tool: 'Use this to review a reading list or to see what's already saved before saving more.' It also provides guidance on when to use verbose mode ('only when you genuinely need the abstract') and suggests a follow-up action with annotate_paper. However, it does not explicitly exclude alternatives by name (e.g., 'use search_papers for discovery'), so it stops short of a full when-not/alternatives treatment.

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 annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It adds useful context beyond annotations by requiring SF_API_KEY and defining pending_hits as 'new matches since the last digest delivery,' which helps the agent interpret results.

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

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

The description is three short sentences with the action and output fields front-loaded, followed by usage and auth details. 'Read-only' is somewhat redundant with the annotations, but the overall structure is tight and each sentence contributes 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?

For a zero-parameter, read-only tool with an output schema and safety annotations, the description covers what the tool returns, who has access, and a primary use case. Mentioning sibling tools like check_watches or preview_watch would improve routing, but nothing essential is missing.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description correctly focuses on output fields instead. This matches the baseline for a no-parameter tool, and no further parameter explanation is needed.

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

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

The description uses a specific verb 'List' with a clear resource ('the authenticated user's watches') and enumerates the returned fields. This makes the operation unmistakable and distinguishes it from watch-mutation siblings like create_watch and delete_watch.

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 recommends using this tool before create_watch to see what is already tracked, giving a concrete usage context. It does not mention alternatives like check_watches or preview_watch, but the stated trigger is clear enough for an agent to route correctly.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important behavioral traits: the match_count cap of 200 and saturation on broad/hot topics, that 'similar' uses a default 0.70 cosine floor, and that the 'cites' relation uses a 30-day window. It even warns how to tune around these behaviors rather than relying on match_count alone.

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 dense but every sentence earns its place: purpose, return contract, ranking defaults, anti-noise tuning, the similarity cap caveat, and authentication/read-only status. The most important framing ('Dry-run ... WITHOUT creating a watch') is front-loaded, and the warning is clearly separated with 'NOTE.'

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

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

For a complex tool with nested criteria and multiple filter modes, the description is remarkably complete. It covers when to use it, how to iterate, what values to expect, what cap behavior to watch for, and how it relates to create_watch. The presence of an output schema and full schema coverage lowers the burden, and the description still exceeds it.

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?

Although the schema already has 100% parameter coverage, the description adds substantial interpretive value: it explains that 'rising' is the default ranking, that min_impact_pct creates a 'what-is-rising-now' watch, and that match_count saturates at 200 for similar filters. This goes beyond the raw schema and helps the agent choose and tune parameters intelligently.

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-resource pair: 'Dry-run a structured filter over recent papers WITHOUT creating a watch.' It clearly frames the tool as the tuning loop preceding create_watch, and the returned fields (window_days, needs_similarity, match_count, sample) make the purpose concrete and distinct from sibling tools like check_watches or create_watch.

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 explains when to use this tool: iterate on a filter 'before saving with create_watch.' It also gives operational guidance for tuning, such as raising min_novelty, switching the collection relation, and using min_impact_pct for an anti-noise watch. The alternative create_watch is named directly, giving the agent a clear decision boundary.

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 annotations already declare readOnlyHint=false and destructiveHint=true, and the description goes beyond them by explicitly stating 'MUTATES', explaining that the paper remains in the library, and adding that the operation is idempotent. It also discloses the SF_API_KEY requirement, which is valuable for invocation.

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

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

The description is compact and information-dense. It front-loads the core purpose, then clarifies mutation scope, idempotency, and authentication in three short sentences. No sentence is wasted.

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 destructive mutation tool, the description covers the essential operational details: addressing by collection_id or collection_name, mutation scope, idempotency, and required API key. An output schema exists, so return values need not be described. The description is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents arxiv_id, collection_id, and collection_name with their meanings. The description adds the 'collection_id OR collection_name' relationship, but this is also present in the schema property descriptions, so the description only minimally enhances parameter understanding.

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

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

The description states a specific verb and resource: 'Remove a paper from a collection.' It also clarifies the scope by distinguishing between removing from a collection versus keeping the paper in the library, which differentiates it from sibling tools like unsave_paper and add_to_collection.

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 gives clear context for when this tool is appropriate: when removing a paper from a collection, and it explicitly notes that the paper stays in the library, implying it is not for removing papers from the library. It does not name sibling alternatives directly, but the scope is clear enough for an agent to select it correctly.

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?

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral detail beyond that: it mutates the library, feeds personalization signals, is idempotent, and requires SF_API_KEY. This gives the agent important operational expectations without contradicting the 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 efficiently structured: main action first, then mutation warning, personalization effect, idempotency, auth requirement, and a pointer to the relevant alternative. Every sentence contributes useful information 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?

For a single-parameter, side-effecting tool with an output schema and annotations, the description covers the essential context: what it does, side effects, idempotency, auth needs, and the closest alternative. Nothing critical is missing 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?

There is only one parameter, arxiv_id, and the input schema already describes it fully with an example. The tool description does not add extra parameter-level detail, so a baseline score of 3 is appropriate when the schema carries the semantic load.

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

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

The description uses a specific verb and resource: 'Save a paper to the authenticated user's Scholar Feed library (bookmark).' It clearly frames the operation as creating a bookmark and even distinguishes it from the sibling add_to_collection, which performs a save plus collection filing. This leaves no ambiguity about what the tool does.

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

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

The description clearly states when to use save_paper: to save/bookmark a paper in the Scholar Feed library. It also names an alternative, add_to_collection, and gives the condition for choosing that instead ('to file it into a named collection in one step'). It does not explicitly exclude other related siblings like like_paper, but the context is clear enough.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that: it discloses the retrieval limit, the recency/style bias that misses canonical papers, the difference between proven citations, forecast impact, and GitHub adoption, and the fact that is_saved=false is meaningful only on authenticated calls. This is a rich behavioral contract that prevents the agent from misinterpreting results.

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 long and uses ALL-CAPS emphasis, which slightly hurts skimmability, but it is well-labeled and information-dense with every section serving a purpose. The front-loaded core definition, followed by retrieval-limit caveats, impact-mode distinctions, and library-state semantics, gives an agent the most important facts early.

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 (27 parameters, 100% schema coverage, and an output schema), the description covers the cross-cutting concerns that no single parameter could convey: retrieval biases, the q-less browse rules, anonymous vs authenticated result differences, and the meaning of saved/read/note_text fields. There is no obvious gap that would prevent an agent from using this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning by synthesizing the three notions of impact and warning that filters like impact_min and min_stars have coverage holes. It also instructs the agent to read each parameter's own documentation, which is appropriate for 27 parameters. It does not need to repeat schema details, and it contributes enough contextual nuance to warrant a 4.

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 opens with a specific verb and resource: 'Search Scholar Feed's 600k+ CS/AI/ML paper corpus.' It immediately clarifies that semantic embedding search is the default, which differentiates it from keyword search and gives the agent a precise mental model of what the tool does. It also names get_foundational_lineage as the complementary tool for finding canonical work, helping distinguish its scope from a sibling.

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 gives explicit when-to-use and when-not-to-use guidance: for canonical work it says to read top abstracts or 'call get_foundational_lineage', and for rising work it says 'Do NOT use it to find the influential/seminal papers... use sort='impactful' instead.' It also warns about the q-less 422 cases and when paired filters are needed, giving agents actionable decision rules.

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?

Beyond the destructiveHint annotation, the description discloses that the operation mutates the library, is idempotent, and cascades by removing the paper from every collection. It also flags the auth requirement, giving full transparency about side effects.

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

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

The description is compact yet information-dense: purpose, mutation warning, idempotency, collection side effect, alternative tool, and auth requirement all fit in a few sentences. Every sentence adds value and the most critical behavior comes first.

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 single-parameter destructive tool with an output schema and relevant annotations, the description is complete. It covers the operation's effects, edge case behavior, alternative route, and authentication, so an agent has everything needed 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?

The input schema fully documents the single arxiv_id parameter, so the description does not need to add much. It does not introduce extra parameter-level detail, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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 'remove' and the specific resource: a paper from the authenticated user's Scholar Feed library. It also differentiates itself from remove_from_collection, making its precise scope obvious.

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

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

It explicitly tells the agent when to use this tool versus remove_from_collection, with a concrete condition: use remove_from_collection if the paper should remain saved. It also notes the SF_API_KEY requirement for authentication.

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 explicitly says 'MUTATES', clearly disclosing that this is a write operation. It also reveals an important side effect: changing criteria replaces the definition and clears pending hits, with the next daily evaluation repopulating them. This goes well beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false.

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 compact and every sentence earns its place. It front-loads the core action and mutation warning, then adds side-effect, tuning, and authentication guidance without unnecessary verbosity.

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

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

For a tool with this complexity—nested criteria, multiple update targets, mutual address options—the description covers the essential operational context: mutation, side effects, default ranking behavior, the preview_watch alternative, and the required API key. The output schema reduces the need to explain return values, and the tool is well-scoped 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%, so the baseline is 3, but the description adds meaningful parameter context: it explains that criteria is a full replacement, that changing it clears pending hits, that 'rising' is the default rank, and that min_impact_pct creates an anti-noise watch. This adds value beyond the raw schema definitions.

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

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

The description clearly states the specific action: updating an existing watch in place, and enumerates what can be updated: rename, novelty_min, or criteria. It also distinguishes itself by mentioning the structured filter retargeting and the address-by-watch_id-or-name, which separates it from create_watch and delete_watch.

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 gives a clear usage context: when you need to modify an already-created watch. It also directs the agent to preview_watch first when tuning criteria, which is a helpful alternative. It does not explicitly spell out when not to use the tool or compare with create_watch/delete_watch, so it stops short of a 5.

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