Oliver's mTOR Atlas

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

Annotations already fully declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description need not restate that. It adds that derived_counts are computed from the relations, which is useful behavioral context, but says nothing about the shape or size of the returned metadata block.

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 compact sentences with the content list front-loaded, so the agent knows what it gets immediately. The second sentence is slightly tangential and introduces derived_counts without clarifying its status, which costs a point.

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 metadata tool with no output schema, listing the returned content (version, snapshot date, counts, legend, citation) is close to sufficient. The unresolved ambiguity about whether derived_counts is a field or a separate operation is the main 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?

The tool takes zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and there is nothing further the description could meaningfully add about inputs.

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 enumerates exactly what the tool returns: dataset version, corpus snapshot date, counts, evidence-code legend, and citation guidance. That is specific and distinguishable from the entity-lookup siblings. It lacks an explicit verb, and the derived_counts sentence blurs whether that is a returned field or another tool.

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: an agent must infer this is the entry point for dataset provenance and citation info. The one concrete pointer is the tie to find_contradictions for comparing derived contested/conflicting counts, but there is no explicit when-to-use or when-not-to-use framing.

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, non-destructive. The description adds real behavioral value: it discloses the return shape (full cards for supporting and conflicting studies) and the dedupe behavior of repeating studies as short cards. The undefined term 'full_card_in' weakens the disclosure slightly.

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 purpose and usage example. The final sentence is largely redundant with the dedupe parameter description but adds the 'full_card_in' naming that the schema lacks, so it still earns some of its space.

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?

No output schema exists, so the description carries the return-value burden. It gestures at cards for supporting/conflicting studies but omits pagination, result limits, or a clear definition of 'full card' vs 'short card', and the unexplained 'full_card_in' field is left dangling.

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 33%; a and b have no schema descriptions. The description partially compensates by stating 'either direction', clarifying that argument order is irrelevant, but never specifies what a and b actually are (IDs, names, entity types). The dedupe semantics are covered by the schema itself.

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 ('Direct curated relations between two entities (either direction)') and gives a concrete question it answers. It is clearly more targeted than siblings like find_relations or get_relation, but never names those siblings to sharpen the distinction.

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 example question ('what is the evidence that A acts on B?') implies the intended use case. However, there is no explicit when-to-use versus find_relations or get_relation, and no exclusions or prerequisites, leaving routing 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 readOnly/idempotent/non-destructive, but the description goes beyond them by describing return-side behavior: status indicating the category, breakdown splitting totals, the conflicting_studies_missing flag, and the named_in_text caveat that 'a mention is not evidence.' It also discloses pagination via next_offset.

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 purpose, then output semantics, then paging and the entity restriction. Sentences are dense and telegraphic but each carries substantive content; 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?

With no output schema and no required parameters, the description should explain the result shape, and it does reasonably well (status, breakdown, flags, named_in_text, truncation hint via brief). Some ambiguity remains around exact response structure, but nothing critical 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 coverage is high (83%), so the schema largely carries parameter meaning. The description adds only the offset-as-next_offset paging instruction and the one-entity restriction; it says nothing about limit's cap, brief, or dedupe, which the schema already documents. 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?

The description states a specific resource and scope: 'Relations the Atlas marks as contested or that carry conflicting studies, with both sides of the evidence.' That clearly distinguishes it from a generic relation lookup, though it never names the sibling (find_relations, get_relation) it should be contrasted with, leaving the differentiation to inference.

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 only implied: it signals the tool is for contested/conflicting relations and notes the optional entity restriction and paging. There is no explicit 'when to use this instead of find_relations' or any exclusion, so an agent must infer the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the agent knows it's a safe read. The description adds 'signed, evidence-linked' and filter semantics but does not disclose pagination behavior, result size caps, or rate limits.

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?

Single dense sentence front-loads the resource and then enumerates filters. No wasted words, though the sentence is long and slightly compressed.

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, no-output-schema tool, description covers most filter intent but omits return shape, pagination (offset/next_offset), and the limit cap that the schema itself notes. Adequate but incomplete.

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 63%; the description compensates by explaining filter dimensions: entity on either end, source/target, effect, contested status, minimum strength. This adds meaningful grouping and intent beyond raw parameter names, though it doesn't clarify the enum codes or limit cap.

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 with a concrete example ("Rheb activates mTORC1") that disambiguates it from siblings like get_relation and evidence_between. The description makes clear this is a searchable, filtered list of relations.

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?

Community guidelines are described (filter by entity, source/target, effect, contested status, strength), which implies when to use it, but no explicit when-to-use vs get_relation or evidence_between. No exclusions or alternatives named.

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), so the description adds the payload shape instead: lab, role, profile URL and short study cards. With no output schema, this is the only source of return-value information, which is genuine added value.

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 front-loaded sentence with no filler; the resource and the identifier forms come before the payload description. Every clause carries 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 get-by-identifier lookup with no output schema, the description covers the returned fields adequately, but omits not-found behavior, whether id/author are interchangeable, and any distinction from search_authors. Adequate, not 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 coverage is 100% and both params ship descriptions with examples, so the schema does the heavy lifting. The description's identifier examples ('claudio-de-virgilio', full name, author-list form, ORCID) reinforce the schema but add no syntax or format detail beyond it. Baseline 3.

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: retrieves ONE profiled author, and enumerates identifier forms (profile id, full name, author-list, ORCID). The word 'One' implicitly separates it from the sibling search_authors, though that contrast is never made explicit.

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 context (fetch a single author when you already have an identifier), but there is no explicit when-to-use statement and no routing to the obvious alternative search_authors for partial/ambiguous lookups. Nothing beyond 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the shape of the payload (linked studies as short cards, pathway relations as one-line claims) and the studies_limit truncation, but says nothing about ambiguity or error behavior when a name matches multiple entities.

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 resource and its scope, with the accepted-key note placed last. Dense but every clause carries information; 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?

With no output schema, the description does the necessary work of describing the returned payload, which is its main strength. It leaves open what happens with zero arguments (nothing is required) and how ambiguous names are resolved, gaps an agent would hit in practice.

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 three parameters are documented in the schema (including the 50-study cap). The description adds only the clarification that id/name/synonym are interchangeable lookup keys, which is modest value over the schema's own 'Alias of entity' note.

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 ('One entity') and enumerates the entity types it covers (gene/protein, complex, drug, disease, process), which clearly separates it from the plural search_entities. It stops short of explicitly naming the sibling it is the singular counterpart of, so an agent must infer the split.

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 clause 'Accepts an id, a name or a synonym' implies you call this when you already have a concrete identifier, versus using search_entities to discover one. There is no explicit when-to-use/when-not statement and no guidance on which of the two identifiers 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 readOnlyHint=true, idempotentHint=true, and openWorldHint=false, making the safety profile clear. The description adds useful content about what the question object contains, but doesn't describe authentication, error behavior, or rate limits.

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 a compact single sentence that front-loads the resource and ID examples, with no wasted words. It could be slightly more structured with a clear when-to-use phrase.

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 read-only tool with one parameter and no output schema, the description covers the content well. However, given 0% schema description coverage, it should specify the expected ID format or describe return behavior more completely.

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 0%, so the sole 'id' parameter is completely undocumented. The description provides example IDs ('H1', 'F2') which add some semantics beyond the raw string type, but doesn't state format requirements or whether 'open' vs 'frontier' IDs differ.

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+resource combination: retrieve 'One open or frontier question by ID', with example IDs, which clearly separates it from list_questions and search tools. However, it doesn't explicitly name alternatives or clarify the open/frontier distinction beyond context.

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 context is implied by 'by ID' and the sibling tools list, but the description does not say when to use this versus list_questions or search_entities.

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 this a safe, idempotent, read-only, closed-world lookup, so the safety profile is covered. The description usefully adds the shape of the returned content, but says nothing about failure behavior (e.g. unknown ID), which is the main remaining behavioral gap.

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 dense sentence with the resource and lookup key front-loaded and the returned fields trailing as a list. No filler, though its telegraphic fragment style slightly reduces readability.

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 enumerating the fields returned (mechanism, boundary conditions, confidence, supporting/conflicting studies). The only material omission is error/miss behavior for a bad ID.

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 0%, so the description carries the burden, and the inline example 'RHEB-MTORC1' communicates the expected ID format, which is more than the bare 'string' schema provides. It stops short of stating whether the ID is case-sensitive or how it is obtained.

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?

Names the specific resource ('one pathway relation') and the lookup key ('by ID'), and enumerates the returned fields (mechanism, boundary conditions, confidence, studies). It implicitly separates itself from the plural sibling find_relations, though it never states that distinction 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?

The ID example ('RHEB-MTORC1') implies you need a pre-known relation identifier, which hints at when to use it, but there is no explicit when/when-not guidance and no mention of find_relations as the discovery alternative for agents that lack an ID.

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 real value by disclosing what comes back (abstract excerpt, extracted findings, linked entities, supported/contradicted relations, related open questions). It stops short of describing error behavior for an unmatched ID or any size/shape limits on the payload.

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 zero filler; the identifying constraint (one study, by known identifier) is front-loaded and the return enumeration follows as a compact 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?

With no output schema, the description carries the burden of explaining the return value and does so adequately by listing the record's constituent parts. The remaining gap — behavior on a missing/ambiguous identifier and whether relations are summarized or inlined — is modest for a read-only lookup 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?

Schema description coverage is 100% and all three parameters are documented there, including their role as aliases of sid, so the schema does the heavy lifting and baseline is 3. The description restates the identifier formats but does not explain the id/study_id aliasing or note that all parameters are optional.

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 ('Full record for one study') and enumerates the record's contents, so an agent can distinguish it from search_studies and the other single-entity getters (get_entity, get_author, get_question) without opening a 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?

The description implies usage by spelling out the accepted identifier space (Atlas ID, PMID, DOI, PMCID), which tells an agent it must already have a known study identifier. However, it never states when to prefer this over search_studies or what to do when the identifier is unknown — usage is implied rather than explicit.

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 safety is covered. The description adds genuinely useful behavior beyond that: results are paged, and still_open is silently shortened at a sentence boundary by default, which is exactly the kind of lossy default an agent must know about or it will quote truncated evidence.

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, front-loaded with the resource and scope before the paging and truncation caveats. 'Paged.' is a maximally economical way to convey a behavior that matters, and no sentence is 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 carries extra weight and does mention the truncated field name and paging model, plus offset/next_offset usage is covered in the schema. Minor gap: the effective limit cap of 50 is stated only in the schema, not in the description, and the frontier vs open-question distinction is not elaborated.

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 80%, so the baseline is 3; the description still adds meaning by explaining the brief flag and naming the resulting still_open_truncated field, which the schema does not surface. The kind enum and limit cap remain schema-only, hence not a 5.

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 resource with scope: 'The Atlas's open questions (evidence gaps with testable hypotheses) and frontier questions', clarifying what an open question actually is. It also differentiates from the sibling get_question by noting that tool holds the full text, so an agent can pick between them 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?

Gives a clear routing rule for full text ('get_question has the full text, or pass brief=false'), which tells the agent when this tool is sufficient versus when to escalate. It does not, however, say when to prefer this over the search_* siblings for discovery, so guidance is strong but not exhaustive.

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 genuine behavioral value beyond them by disclosing the two-bucket response shape: results contain authors with a profile page, while in_author_lists are bare name matches without a profile. It does not mention result caps or pagination, but those live in the 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?

Compact and front-loaded: the query capability comes first, the return-shape explanation second. Slightly dense parenthetical stacking, but every clause carries information and nothing is 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?

There is no output schema, so the description's explanation of results vs in_author_lists does the work of describing the return values, and the schema handles limits and pagination. For a read-only search tool, an agent has everything needed to call it and interpret the response.

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 limit/offset/query are already documented, and next_offset pagination is spelled out in the offset description. The description's mention of accepted query forms largely restates the schema's own examples, so it adds little beyond 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 gives a specific resource (people/authors in the Atlas) and enumerates the exact query dimensions (full name, author-list form, ORCID, lab), which makes the tool's intent unambiguous. It does not, however, explicitly contrast itself with the sibling get_author, so an agent must infer when to search versus fetch.

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?

Acceptable query forms are implied through the parenthetical examples ("Claudio De Virgilio", "De Virgilio C", ORCID, lab), which gives practical guidance on how to call it. But there is no statement of when to prefer this over get_author or search_studies, and no exclusions are given.

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/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: results carry a match_field indicating name, synonym, or description provenance, which is not derivable from the annotations or schema. It stops short of describing result ordering or pagination behavior beyond what the schema says.

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, zero filler, and the search scope is front-loaded before the result-shape and match-parameter guidance. Every clause adds 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 search with full annotation coverage and full schema descriptions, the description supplies the one thing the schema cannot: what the match_field in each result means. Pagination (next_offset) and the 100-result cap are already handled by the schema, 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?

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by framing the match parameter's practical consequence ('leave out description-only hits') and by tying the returned match_field values back to the same name/synonym/description taxonomy, which helps an agent choose the parameter value 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?

States a specific verb+resource (find genes/proteins, complexes, drugs, diseases, processes, nutrients, outcomes) and the matching basis (name or synonym). The enumerated entity types make it unmistakably distinct from search_authors and search_studies among the 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?

Gives one concrete usage rule (use match="name" to exclude description-only hits), which is a real when-to-use hint. However, it never states when to reach for this tool versus get_entity, find_relations, or the other search_* siblings — usage context is implied rather than explicit.

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 safety is covered. The description adds genuine behavioral detail: the exact fields matched, the special PMID/DOI short-circuit behavior, and the shape of the result ('summary records with evidence codes and URLs'). It omits the 50-result cap, but that is disclosed in the 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, front-loaded with purpose and filters before the field enumeration. The long third sentence listing searchable fields is dense but each item is decision-relevant, so little 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?

With no output schema and 7 optional parameters, the description compensates by naming the return format and the identifier special case. Pagination is delegated to the offset schema description, which is a reasonable split, though a brief note on result volume/next_offset would close the remaining 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?

The description adds meaning beyond the schema: it maps the entity filter to gene/drug/disease and clarifies author matching accepts both the author-list form "Sabatini DM" and full names. Evidence code, year range and keyword semantics are named, giving conceptual coverage of most of the 7 parameters on top of the 71% 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?

States a specific verb (search) and resource (curated studies), then enumerates the filter dimensions (keywords, evidence code, linked entity, year range) and the searchable fields. An agent can distinguish it from get_study (single record) and from search_authors/search_entities 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?

Usage is implied through the filter list and the note that a PMID/DOI query returns that study, which tells the agent a lookup-style query is valid here. However, it never states when to prefer get_study over this, nor any exclusions or prerequisites, leaving routing to inference.

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