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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: deduplication of overlapping section citations, inclusion of section links, and the default all-works behavior when ids are omitted.

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 supported styles, followed by the id semantics and the no-id fallback. Every sentence carries information, though the middle sentence is dense enough to require a second read.

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 still conveys what comes back (a reference list, deduplicated, with section links, or one reference per work). Combined with the fully documented two-parameter schema, 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it explains that "ids" can be either section ids (yielding deduped references plus links) or source ids (citing whole works). It also confirms the default style when none is passed, which the schema only parenthetically 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 ("Format references for works in the library") and enumerates the supported styles, so an agent knows exactly what it produces. It does not explicitly differentiate itself from siblings like list_sources or search, so it falls just 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?

Clearly lays out the three invocation modes: pass section ids to get a deduplicated list plus links, pass source ids to cite whole works, or pass nothing to get every work. It gives strong context for each mode but names no exclusions or alternative tools for related needs.

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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results can be restricted to one language or one work, and the return payload includes the originating section, packages, a link, and a citation — valuable 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?

Three dense sentences, front-loaded with the core action and scope, then the usage boundary, then the return shape. No filler, though the middle clause is slightly run-on and could be tightened.

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 correctly compensates by describing the return payload (code blocks plus section, packages, link, citation) and the restriction options. Together with the 100%-covered schema and clarifying annotations, an agent has everything needed to call 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 description coverage is 100%, including detailed enum labels for every source work, so the schema already carries the parameter meaning. The description only restates the language/work restriction at a high level and adds no syntax or format detail beyond the schema; 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+resource ('Get runnable code from the library') with an explicit scope (statistical, econometric, causal inference, or ML tasks) and language range. It also draws the boundary against an explanation-style sibling by saying it 'returns code with brief context, not an explanation of the method,' which lets an agent separate it from choose_method.

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 positive trigger: 'Suited to requests for code that carries out a named estimator, test, or modeling step.' It also states a negative condition (not an explanation of the method), but never names the alternative tool (e.g., choose_method) or when to prefer it, stopping short of a full when/when-not/alternatives statement.

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=true, idempotent=true, destructive=false and closed-world, so the safety profile is covered. The description adds genuinely new context by disclosing the return shape (ids, link, snippet, contained code languages, citation) which, with no output schema present, is the only place an agent learns what comes back.

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?

Structure is front-loaded: purpose first, return contract second. The long parenthetical topic list is verbose but earns its place as discovery vocabulary for a broad corpus. Two sentences, no filler, only mild bloat in the enumeration.

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 search tool with full schema coverage and no output schema, the description supplies both the corpus scope and the return contract, which is everything an agent needs to invoke it correctly. No annotated safety behavior or parameter is left unexplained.

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% and the enumerated source/language values are fully documented in the schema, so the description does not need to compensate. It adds nothing about how limit interacts with ranking or how language acts as a preference rather than a hard filter, so 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 states a specific verb (search) and resource (sections of textbooks and an R package on research methods/data analysis), and enumerates the topical corpus, so an agent knows exactly what is being searched. It does not, however, distinguish itself from siblings like get_code or cite, which also surface library content.

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 topic inventory and the query parameter example ('staggered difference-in-differences with never-treated controls'), which signals the intended retrieval use case. There is no explicit when-to-use versus when-not guidance, and no sibling (get_code, cite, choose_method) is named as the alternative for adjacent needs.

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