Research Methods Library

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

Annotations cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description needn't restate that. It adds genuine value by disclosing the return shape — candidate methods with when-to-use, assumptions, R/Python packages, and library sections — which is important since no 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?

Two sentences, each earning its place: the first names the domains and purpose, the second covers inputs and outputs. No repetition of the title or annotations, and the purpose 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 no output schema, the description carries the return-value burden and does so adequately, while the fully covered schema handles parameters and annotations handle safety. 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 description coverage is 100%, so question, limit, and language are already documented in the schema, making 3 the baseline. The description adds meaning by explaining what the 'question' parameter should contain (setting plus treatment assignment), but says nothing about limit or language.

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 (recommend) and resource (statistical/econometric/causal inference/ML methods) scoped to a research question. It is clearly distinguishable from siblings like search, fetch, get_code, and cite, which do retrieval rather than method recommendation.

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?

Tells the agent exactly what context to supply (question, data structure such as cross-section/panel/time series/experiment, treatment assignment, outcome), which is practical invocation guidance. It does not name exclusions or alternative tools, but no sibling appears to overlap this function, so the gap is minor.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: results are deduplicated, section links are returned alongside references, and omitting ids silently expands scope to the entire library.

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 dense sentences, front-loaded with purpose then invocation modes, with zero filler. The no-ids fallback is placed last, which matches its role as the catch-all case.

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

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

With no output schema, the description carries the return-value burden and does so: it names what comes back (reference list, section links) and how it behaves (deduplicated). Nothing needed to invoke 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 baseline is 3, but the description goes further by explaining that the same 'ids' parameter accepts two different id kinds with different resulting behavior (section ids vs source ids), which the schema only hints at. The default apa style is also restated usefully in prose.

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+resource ('Format references for works in the library') and enumerates the exact supported styles. This is clearly distinguishable from siblings like fetch, search, and list_sources 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?

Explicitly lays out three invocation modes: section ids (deduplicated list plus section links), source ids (whole works), and no ids (every work in the library). That is strong conditional guidance, but it never names an alternative tool or a when-not-to-use case, 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.

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: the return is Markdown containing code, a section URL and a citation, and long sections are paginated with the next part's id named in the text. It omits any error behavior for bad ids.

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 short sentences, each doing distinct work: purpose, return shape, pagination. The purpose is front-loaded and there is no filler or repetition of the title.

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

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

With no output schema present, the description correctly carries the return-value burden by naming the Markdown payload, URL and citation, and it explains the pagination contract an agent needs to fetch subsequent parts. It is nearly complete for a one-parameter read tool, lacking only failure-mode guidance.

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 a single required parameter whose schema description already includes a concrete example id at 100% coverage. The description only restates that the section id is the lookup key, adding no format or syntax detail beyond the schema, so the baseline 3 applies.

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 ("Read one section of the library by its section id") and immediately scopes it, which separates it from broad siblings like search. It does not explicitly contrast itself with get_code or cite, so differentiation is implied rather than stated.

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

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

The phrase "by its section id" implies the precondition for calling it, and the note about long sections arriving in parts with a next-part id is genuinely actionable usage guidance. However, it never says when to use this instead of get_code or search, nor what to do when an id is unknown.

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=true, idempotent=true, non-destructive, closed-world, so the safety profile is covered. The description still adds genuinely useful behavioral context absent from structured data: there is no output schema, yet it discloses the return shape (code blocks plus source section, packages used, link, and citation). It does not, however, mention result limits or behavior when no match is found.

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

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

Two sentences, front-loaded with purpose and followed immediately by the return contents; nothing is padded. It could be marginally tighter, but every clause conveys 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?

With no output schema, the description compensates by enumerating the return payload, and all four parameters are fully covered by the schema. The remaining gap is sibling differentiation (search/fetch overlap) and default/limit behavior, which keeps it just short of complete.

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

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

Schema description coverage is 100%, so every parameter (topic, limit, source, language) is already documented in the schema, and the description adds only a marginal restatement of the supported languages. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a concrete verb (get) and resource (runnable code from the library) and scopes it to statistical, econometric, causal inference, and ML tasks across R/Python/Julia. It is clearly not a generic search or fetch, but it never explicitly contrasts itself with the sibling 'search' tool, which an agent could plausibly reach for instead.

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

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

There is no when-to-use/when-not guidance and no routing signal relative to siblings like search, fetch, or cite. The topic examples ('Callaway and Sant'Anna group-time ATT') hint at the intended query shape, but choosing this tool over 'search' is left entirely to 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing the shape of the returned records (topics, languages, licenses, links, citation info), but says nothing about result size or pagination for a full-library listing.

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

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

A single sentence with no filler, front-loading the verb and resource before the list of returned attributes. Every clause 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 no output schema, the description must carry the return-value burden, and it does so by naming the fields each entry contains. The remaining gap is the absence of any hint about catalog size, ordering, or pagination behavior.

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 baseline is 4. The description's field enumeration concerns outputs rather than inputs and does not create any ambiguity about 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?

States a specific verb ("List") and resource ("the books and packages in the library") and even enumerates the fields returned, so the agent knows exactly what this tool produces. It does not distinguish itself from the sibling `search` tool, so it falls short of a 5.

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

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

There is no statement of when to use this versus `search`, `fetch`, or `cite`, and no prerequisites or exclusions. The only signal is the imperative "List," which implies a full-catalog enumeration, but that is left to 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful context beyond that by disclosing the return contents (ids, link, snippet, code languages, citation), which matters because there is no output schema. It does not describe ranking or scoring behavior.

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

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

Two sentences, front-loaded with the purpose followed by the return shape. The long parenthetical topic list is dense but earns its place by telling the agent what content is matchable; nothing else is wasteful.

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

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

With no output schema, the description compensates by stating what a result contains, and it covers the searchable corpus. Combined with the fully documented schema, an agent has what it needs; only the ranking behavior and the absence of sibling routing leave minor gaps.

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

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

Schema description coverage is 100%, so all four parameters (query, source, language, limit) are already documented in the schema. The description adds no syntax, format, or behavior detail for them, so the baseline 3 applies.

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

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

The description gives a specific verb (search) and resource (sections of textbooks and an R package on research methods), and enumerates the covered domains so an agent knows the corpus scope. It does not explicitly contrast with siblings like get_code or fetch, but the retrieval-of-sections scope is unambiguous.

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: it reads as the discovery entry point for the library, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as choose_method, cite, get_code, or list_sources. An agent can infer its role but must decide on its own when a direct fetch or code lookup is preferable.

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