Inciteful

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: edges are directional (citing → cited) while traversal is bidirectional, and hop counts land in provenance.hops. It stops short of noting path explosion, timeouts, or result caps for extended mode.

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 compact sentences, front-loaded with the core action, then output shape, then the one optional flag, closing with the motivating use case. No sentence is redundant.

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, return values need not be spelled out, and the annotations carry the safety profile, so the description covers what remains: directionality semantics and the extended flag's effect. Minor gaps around performance/limits in extended mode keep it from a 5.

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 restates the accepted identifier formats already documented in the schema, but does add meaning for extended by specifying the target ('aiming for at least 5' longer paths), which is more concrete than the schema's 'Also return longer paths.'

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 — 'Find citation paths between two papers' — and clarifies the semantic model ('treating each citation as a link in either direction') plus the practical payoff ('shows how two lines of work relate'). It is clear on its own, though it never names the adjacent siblings (query_citation_graph, explore_citation_network) to draw the boundary 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?

Usage is implied rather than stated: the reader infers this is for pairwise connectivity questions and that extended=true is for weakly connected works. There is no explicit when-not-to-use guidance or pointer to the sibling graph tools, which matters given query_citation_graph and explore_citation_network overlap in territory.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that: an uncached graph 'can take a minute to build', limit caps at 100, and results carry provenance and diagnostics. It omits auth/rate-limit behavior and says nothing about failure modes for unresolvable seeds, so it is good but not exhaustive.

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

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

Nearly every clause carries information, but it is delivered as one dense semicolon-chained block with no front-loading of the most decision-relevant facts (enum semantics, filter applicability). It reads as a wall of text an agent must parse rather than a structured summary, though little is genuinely 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 an 8-parameter, enum-heavy tool with an output schema, the description covers the seed format, every analysis mode, filter scope and stemming rules, the limit cap, latency expectations and provenance in results. Nothing an agent needs to invoke it correctly appears 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?

With only 50% schema coverage, the description compensates heavily: it defines each analysis mode's meaning (enum values are otherwise opaque in the schema), explains that title filters match titles only with Porter stemming, notes title_none requires title_all or title_any, caps limit at 100, and states that title/year filters apply to graph analyses but not to references/citations.

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

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

The opening clause names a specific verb and resource ('Map a field by its citations rather than its keywords') and immediately scopes it to the depth-2 Inciteful graph around 1–500 seed papers. It contrasts itself against keyword search, which cleanly separates it from siblings like search_literature.

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 clear selection axis (citation-based vs keyword-based) and explains what each of the nine analyses is for, so an agent can pick 'similar' vs 'important' vs 'reviews'. It stops short of explicitly naming sibling tools such as query_citation_graph or connect_papers as alternatives, so routing between those still needs inference.

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 establish read-only, idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds real value beyond that: entries come back as separate rows rather than a finished file, entries must be joined with a blank line, and unmatched inputs surface in an 'unresolved' collection — none of which the annotations convey.

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 sentences, front-loaded with the capability, then the gotcha about row joining, then the failure mode. Every sentence carries information an agent needs; nothing is redundant with the title or schema.

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

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

An output schema exists, so return-value structure need not be restated, and the description still flags the 'unresolved' field an agent should check. For a two-parameter, no-nesting formatting tool with full annotations, nothing needed to call it correctly is missing.

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

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

Schema coverage is 50% (only 'ids' is documented in the schema), so the description must carry the load for 'format'. It does: it names both output formats, enumerates the four accepted identifier kinds, and restates the 1–100 bound, adding meaning beyond the schema's minItems/maxItems constraints.

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 artifact (build BibTeX or RIS citations) plus the accepted identifier types and the 100-item ceiling, which is far more precise than the title alone. It does not name or contrast any sibling tool, so an agent must infer that this is the only export/formatter tool among fetch/query 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?

Usage is implied rather than stated: the description reveals this returns rows rather than a file, which tells an agent it must assemble the output itself, and that is useful context. There is no explicit when-to-use routing, no statement of when a sibling like get_papers would be better, and no note on prerequisites such as resolve failure handling.

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 readOnly/idempotent/openWorld, so the description is free to add genuinely new behavior: the algorithm changes at the 15-seed threshold, seeds are excluded from results, scores are only comparable within a single result set, and unresolved seeds appear in diagnostics. These are non-obvious traits an agent could not derive from annotations or schema.

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?

It is front-loaded with purpose and input contract, and nearly every sentence carries information. The middle technical run ('Adamic/Adar plus Salton co-citation on a depth-1 citation graph') is dense jargon in a single unbroken paragraph, which slightly hurts scanability.

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 need no explanation, and this is a read-only tool with annotation coverage. The description covers input format, algorithm-dependent behavior, scoring comparability caveats, and error surfacing via diagnostics - nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 50%, and the description compensates well: it explains the 2-15 reciprocal-rank merge versus the synthetic-paper approach above 15, which materially changes how seeds should be chosen, and it restates the limit ceiling. The 50% gap is the undocumented limit default, which is low-impact.

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+resource and mechanism: 'Ranks papers by their citation links to the seeds, which surfaces related work that keyword search misses.' That last clause explicitly distinguishes it from keyword-based siblings such as search_literature, so an agent can pick it without opening either schema.

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

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

It establishes the triggering condition (you have seed papers; you want related work keyword search misses) and the input contract of 1-500 seeds. It does not name or route to concrete alternatives among connect_papers, explore_citation_network, or query_citation_graph, so the agent must infer which citation tool to prefer.

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 readOnly, idempotent and openWorld, so the description only needs to add context — which it does by disclosing the batch limit and, importantly, the partial-failure behavior ('Inputs it cannot match come back in unresolved with a reason'). It does not cover rate limits, auth requirements, or ordering of 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 identifier formats and returned fields are front-loaded in the first sentence, with scope exclusion and error behavior following. It is dense but every clause carries information; the field list is slightly long given an output schema 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 a single-parameter batch lookup with full annotation coverage and an output schema, this leaves nothing an agent needs to call it correctly: accepted identifiers, batch cap, scope exclusion, and unresolved-input handling are all present.

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% and the single parameter already documents all four accepted identifier forms, so the baseline is 3. The description adds only the 'W…' OpenAlex prefix hint and the 1–100 cap, which largely restate 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?

States a specific verb and resource ('Fetch OpenAlex records ... by DOI, OpenAlex ID (W…), PMID or PMCID') and enumerates the returned payload. The clause 'It does not use the citation graph' separates it from the graph-oriented siblings without naming one.

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 does not use the citation graph' implicitly routes citation-graph needs to query_citation_graph/explore_citation_network, and the batch cap of 100 gives a concrete usage boundary. No sibling is named explicitly and there is no explicit when-not guidance, so it stops short of 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 readOnly/idempotent annotations, it discloses row-return precedence and the 500 cap, the absence of an edge table (so no paper-to-paper citation edges), NULL semantics for isolated papers, and the subtle synthetic W0 behavior with multiple seeds that silently breaks cocite and shifts adamic_adar. These are exactly the traps that produce wrong results silently, and they are stated up front.

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?

It is long, but it is clearly sectioned into purpose, rules, schema, caveats, and examples, and the single most important constraint is front-loaded in the first sentence. A few schema lines are dense but none are filler given that this is a general-purpose SQL surface.

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 free-form SQL tool the description carries the full burden of the queryable schema, and it delivers that plus documented gotchas and runnable examples. An output schema exists, so the absence of return-value prose is not a 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what seeds actually do (they determine the graph that is materialized, depth 2) and clarifies the limit resolution chain. The examples also demonstrate the sql parameter's practical shape beyond 'a single SELECT statement'.

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?

It names a specific verb and resource — 'Run your own read-only SQLite query on the citation graph' — and immediately bounds scope to a graph built around 1–500 seed papers at depth 2. That framing makes it distinguishable from siblings like explore_citation_network or search_literature without opening any schema.

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

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

It gives concrete operating rules (single SELECT only, OFFSET and LIMIT a,b rejected, page with narrower WHERE or ORDER BY) and two worked examples that show intended use. What's missing is an explicit routing statement such as 'prefer get_papers/explore_citation_network for simple lookups; use this only for aggregation the other tools can't express'.

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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior (chunked retrieval, the next_offset continuation protocol, licence and sha256 in the response, and the open-access-links fallback in rows). That is meaningful context beyond the annotations, though it does not mention rate limits or what happens on a failed/unknown ID.

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 sentences, front-loaded with the core action and pagination contract, followed by return-value and fallback notes. Every clause carries information an agent needs; nothing is repeated from the 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 3-parameter read tool with an output schema already present, the description covers the retrieval mechanics, the pagination termination rule, the degraded-mode return shape, and accepted ID formats. An agent can invoke and iterate this tool correctly without further guessing.

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 67% schema coverage (max_chars has no schema description), the description compensates by documenting the 40000 cap and the offset/next_offset pagination loop, including the termination condition. It also enumerates the accepted identifier forms (DOI, OpenAlex ID, PMID, PMCID) beyond the schema's single-line note, and introduces next_offset, which is not an input parameter at all.

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 — reading the full text of an open-access paper from PubMed Central (PMC BioC) — and scopes it to open-access content, which sets it apart from search_literature, get_papers and the citation-network siblings. It stops short of naming an alternative tool for the case where the caller wants metadata rather than full text, so it is clear but not fully sibling-differentiated.

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 concrete calling context: pass offset=0 to start, continue from next_offset until null, and it flags the fallback behavior when PMC has no text. There is no explicit statement of when NOT to use this tool or which sibling to prefer for metadata-only lookups, which keeps it below 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?

Annotations only declare safety properties (read-only, idempotent, open-world), so the description carries the rest and does: it discloses that the index is live rather than a snapshot, that matching covers titles/abstracts/full text where available, that results are relevance-ranked, and that rows omit abstracts and authors — a limitation that materially affects downstream tool choice.

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

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

Front-loads the identity and scope in the first sentence, then usage, then caveats, then return shape — a sensible priority order. Despite its length, each sentence supplies a distinct fact (source, ranking, alternative routing, return fields, pagination, limit cap) 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?

For a six-parameter, open-world search tool with an output schema, this covers what to call it with, when to prefer a sibling, what the ranking means, what comes back and how to page. The only real gap is the year-range filter semantics, which is minor against otherwise thorough coverage.

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

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

Schema coverage is 50%: query, cursor and open_access are documented in the schema, while limit, year_from and year_to are not. The description repeats the limit cap and explains cursor paging but adds little beyond the schema on those, and never explains what year_from/year_to filter or whether bounds are inclusive, leaving two parameters undocumented anywhere.

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 ("live keyword search of OpenAlex") and immediately scopes it against the alternative ("not of the citation graph snapshot"), which is exactly the distinction an agent needs given siblings like query_citation_graph and explore_citation_network.

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 an explicit when-to-use ("find seed papers when you have a topic but no DOIs yet") and an explicit when-not, both as an exclusion ("not a systematic search") and as a named alternative behavior ("keyword matches miss related work that uses different words, which the citation graph finds"). The routing decision is fully determined.

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