Research Methods Library

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

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds value beyond that by disclosing the return shape: candidate methods with applicability conditions, key assumptions, R/Python packages, and pointers to library sections. It does not discuss limits (e.g., the default of 3 results) beyond what the schema states.

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 definition is a single dense paragraph but is well front-loaded: purpose and task families come first, input requirements next, return contents last. Every clause adds a distinct capability, though the length borders on an enumeration dump rather than tight prose.

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 describing what is returned (methods, applicability, assumptions, packages, library sections). Inputs are fully documented in the schema, and the annotations carry the safety profile, so nothing an agent needs 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 adds meaning beyond the schema by specifying the content the 'question' parameter should carry (data type, assignment mechanism, outcome) rather than only the schema's single example. It also implicitly ties the 'language' parameter to the packages returned.

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 (recommend) and resource (statistical, econometric, causal inference, or ML methods) and enumerates the concrete task families it covers, from test selection to power analysis to predictive modeling. An agent can tell instantly that this tool maps a research question to candidate methods, distinct from the search/fetch/cite 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?

It gives clear when-to-use coverage by enumerating the triggering scenarios ('which statistical test or model fits the data', 'how to estimate a causal or treatment effect', 'how to analyze an A/B test'), and it specifies what the caller must describe (question, data structure, treatment assignment, outcome). It names no exclusions or alternative tools, but the sibling set contains no competing recommender, so context is otherwise 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 readOnly/idempotent/non-destructive annotations, the description discloses that section ids are deduplicated and include section links, that source ids cite whole works, and that omitting ids returns every library work. It does not discuss limits, error behavior, or output shape in detail.

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, front-loaded with the core action and styles, then the id modes, then the default. Every sentence carries operational information with no repetition.

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 citation formatter with no output schema, the description covers the important behaviors: supported styles, section-vs-source id distinction, deduplication, extra section links, and the no-id default. Nothing needed to invoke 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?

Although schema coverage is 100%, the description adds real meaning beyond the schema by explaining the consequence of each id type: section ids give deduplicated references plus section links, source ids give whole-work citations, and no ids default to the entire library. The style enum is already covered by the schema, but the ids semantics are substantially clarified.

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: formatting references for library works in six named citation styles. It is clearly distinct from siblings like search or fetch, but it does not explicitly name an alternative or contrast its role, so it falls short of the top score.

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 clearly explains the three usage modes: section ids produce a deduplicated list with section links, source ids cite whole works, and no ids cite everything. It does not say when to use cite versus siblings such as fetch or search, nor does it state exclusions.

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

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

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, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds valuable return-shape context — code blocks with originating section, packages used, a link, and a citation — which is behavior not captured by annotations. Lacks rate/pagination detail.

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 core verb and resource in the first sentence, then layers in scope and return details. Slightly verbose with four sentences, but each adds distinct information without repetition.

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 supplies the return format (code blocks with section, packages, link, citation), and annotations cover the safety profile, so an agent has what it needs to call the tool correctly. Minor gaps around pagination/limit behavior remain but are low-impact.

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 topic, limit, source, and language thoroughly. The description only lightly reinforces this ('Results can be restricted to one language or one work'), adding little beyond the enum descriptions already present.

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 ('Get runnable code from the library') with a clear domain (statistical, econometric, causal inference, ML tasks) and languages. It also differentiates itself from an explanation-oriented sibling by noting it returns 'code with brief context, not an explanation of the method,' though it never names that sibling 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?

Gives a clear usage condition ('Suited to requests for code that carries out a named estimator, test, or modeling step') and an implicit exclusion ('not an explanation of the method'), which steers an agent toward this tool for concrete code rather than method explanations. It stops short of naming the alternative tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered structurally. The description still adds real behavior beyond that: no parameters are required and the call returns one entry per work, which tells the agent the result granularity in the absence of an output 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?

Three sentences, zero filler: the field enumeration, the usage context, and the calling/return behavior each carry weight. The purpose and scope are front-loaded in the first clause.

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 no-parameter, read-only list tool with no output schema, the description compensates by naming the returned fields and the return granularity (one entry per work). Nothing an agent needs to decide whether and how to call it 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?

There are zero parameters, so the baseline is 4. The description correctly states 'takes no parameters,' which is consistent with the empty schema and prevents an agent from hunting for filter arguments.

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 (list the works in the library) and enumerates exactly what each entry contains — topics, code languages, section counts, licenses, links, citation info — so an agent knows the shape of the result. It does not explicitly name a sibling (search, fetch, get_code) to contrast against, 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?

"Suited to questions about what the library covers or which work to consult" gives a clear use context and implicitly rules out the lookup-oriented siblings like get_code or cite. There is no explicit when-not-to-use statement or named alternative, 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, closed-world, non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing the return contents (ids, link, snippet, code languages, citation) in the absence of an output schema, and by defining the corpus boundary. It does not discuss ranking, relevance behavior, or what happens when no sections match.

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-loaded with the search verb and resource, followed by a return-value sentence that earns its place. The mid-sentence topic enumeration is long and somewhat sprawling, but it doubles as corpus scoping rather than pure 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?

With no output schema, the description compensates by stating exactly what a result contains (id, link, snippet, code languages, citation), which is what an agent needs to chain into fetch or cite. Combined with 100% schema coverage on the four parameters and annotations covering safety, nothing essential to 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 description coverage is 100%, so the schema already documents query, limit, source, and language, including the full source enum with work titles. The description mentions the corpus at a high level but adds no syntax, ranking, or preference semantics beyond the schema (e.g., how 'language' preference interacts with results). Baseline 3 applies when the schema carries the parameter burden.

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 concrete verb-plus-resource: it searches "sections of textbooks and an R package," then enumerates the topical scope (regression, causal inference, econometrics, etc.). An agent can tell this is full-text retrieval over a curated corpus rather than document retrieval of a whole work. It never names the sibling tools (fetch, get_code, cite), so the differentiation is inferable but not 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?

Usage is implied by the scope statement: search this corpus when the question touches research methods, statistics, causal inference, or the listed applied domains. There is no explicit when-not guidance and no routing to alternatives such as fetching a full section once an id is found, or using get_code for runnable code. An agent must infer the search-then-fetch workflow.

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