PepBank Peptide Research MCP: BPC-157, Retatrutide and Tirzepatide Studies and Trials

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

Beyond the readOnly/idempotent annotations, the description discloses the truncation limits (largest 8 outcome groups, or 5 for 4-5 peptides; 2 top findings, or 1 for 4-5 peptides), the no-ranking policy, the evidence-class taxonomy, and an important null-semantics caveat that a 0 human count does not mean no human study exists. That is real behavioral context the annotations cannot carry; it stops short of covering error behavior for unresolvable peptide names.

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 critical scoping and alternative-tool sentences are front-loaded, and the caveats each earn their place. The two parallel 'Each MCP column includes...' sentences are slightly repetitive and the phrase 'MCP column' is unexplained jargon, but there is no filler.

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

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

For a 2-parameter, capped-comparison tool with an output schema and full annotation coverage, the description supplies everything an agent needs: scope, limits, interpretation caveats, and alternative routing. Return-value explanation is a bonus rather than a requirement given the output schema exists.

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, and the description does add meaning by tying peptide count to output caps. However, the 'view' enum (compact/full) is never mentioned in the description, leaving its effect on result detail undocumented outside the terse enum description 'Default compact.'

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

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

The opening sentence names a specific verb (return) and enumerates the exact payload: identity, evidence counts, outcome groups, top findings, plus shared outcome groups for 2-5 peptides. It also explicitly distinguishes itself from get_peptide_brief, so an agent can tell the batch-comparison tool apart from the single-peptide tool without opening either schema.

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

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

It gives a positive trigger ('Use this for a comparison in one call') and three named alternatives with their selecting conditions: get_peptide_brief for one peptide, get_evidence_map for all outcome groups, search_findings for more findings. Routing is fully determined by the description.

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 as a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context beyond that: sequence ordering, newest-page default, and next_since_seq as the continuation position. It does not describe rate limits or filtering behavior, but the core operational semantics are clear.

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?

Four sentences, each front-loaded and purposeful: purpose, sync usage, pagination default, and alternatives. No redundant or filler wording.

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

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

An output schema exists, so the description need not explain return values in detail. It covers sequencing, pagination continuation, default behavior, and alternative tools, which is complete for a change-feed synchronization 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 coverage is 100%, so the schema already documents limit, since_seq, and entity_type. The description adds meaning around since_seq pagination and continuation, but it does not elaborate on limit or entity_type, so it remains at the baseline level for parameter semantics.

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: return record change events in sequence order. It also distinguishes itself from siblings by naming get_freshness and get_record with their distinct roles, so an agent can select it without opening other schemas.

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 explicit usage conditions: synchronize data after since_seq, use 0 for full history, omit since_seq for the newest page. It also names alternatives for adjacent needs (get_freshness for import times, get_record with as_of_seq for historical records).

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 a safe read (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add provenance and edge-case context, which it does: results are community-reported rather than trial-tested, seller pages are never accepted as sources, each line carries its sources, and a peptide may legitimately have no record. It does not discuss result volume, pagination, or how conflicts between sources are resolved, which keeps it just short of a top score.

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 sentence is long but front-loaded: the return payload is stated first, then provenance caveats, then the usage pointer, then view semantics. Nearly every clause earns its place, though the trailing view explanation could arguably sit closer to the peptide content description rather than at the very end.

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 only two fully documented parameters and an output schema present, the description covers everything the agent still needs: what is returned, the reliability caveat, source-quality exclusion, the empty-result case, the cross-tool pairing, and the compact/full tradeoff. Nothing material for a correct call 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% and the peptide parameter already documents name/alias/slug/ID with examples, so the baseline is 3. The description adds meaning only for view — 'compact keeps key lines' versus 'view="full" returns every line' — which is a genuine but small increment over the schema's terse 'Default compact.'

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

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

The description names a specific verb and resource ('Return what community sources report about how people use one peptide') and enumerates exactly what comes back: uses, regimens with route/amount/frequency/duration, side effects, cautions, and regulatory notes. It also distinguishes itself from get_peptide_brief by pointing to that tool's studied_doses, so an agent can tell the two apart without opening either schema.

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

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

It gives explicit routing guidance: 'Use it for use, dose, cycle and compounding questions, together with studied_doses from get_peptide_brief.' The caveat 'Community-reported, not tested in trials' implicitly steers efficacy/trial-evidence questions toward the evidence siblings, but no sibling is named as the explicit alternative for trial data, so the when-not side is left implied rather than stated.

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), yet the description adds substantial interpretive context: counts reflect administered findings only, the endogenous block measures the body's own peptide and is not evidence about taking it, and a 0 human count means none within the filters rather than no study existing. These caveats prevent real misreadings of the output. It stops short of describing ordering, pagination or response shape, but with an output schema present that is a minor 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?

Purpose and scope are front-loaded in the first two sentences, followed by alternatives and then interpretation caveats. Every sentence carries information, though the block on evidence classes and the zero-count caveat could be tightened given the tool takes only two parameters.

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?

Given a simple two-parameter read tool with full schema coverage and an output schema, the description covers the interpretive essentials an agent needs. The remaining gaps are the effect of the 'view' mode and the dangling reference to 'filters' that the schema does not expose.

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 both parameters are already documented, which sets the baseline at 3. The description adds nothing about the 'view' parameter (compact vs full) or how peptide name/alias/slug/ID resolution behaves, and it references 'filters' that do not exist among the parameters, which is slightly confusing. The meaning it adds is about count semantics, not parameter usage.

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 ('Return checked finding counts for one peptide') and enumerates the exact breakdowns produced: outcome group, evidence class, direction, plus year, design and safety counts. It also names the siblings it is not (search_findings, compare_peptides), so an agent can distinguish it 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 says when to use this tool ('inspect evidence coverage and gaps') and when not to, routing to search_findings for individual claims and source sentences and compare_peptides for multiple peptides. The alternatives are named with the condition that selects each.

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 description's job is field-level caveats — and it delivers two: lag_hours measures time since success rather than upstream backlog, and source_latest_known is not yet reported and remains null. That prevents a common misreading of a null value. It stops short of anything about refresh cadence, caching, or how stale the stored results themselves may be.

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?

Four short sentences, zero filler, front-loaded with what is returned before the alternative-tool routing and the field caveats. Each sentence carries distinct information an agent would otherwise have to guess at.

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?

A zero-parameter read tool with an output schema and full annotation coverage needs little more than this: what it returns, when to pick it over siblings, and the two gotchas in the payload. Nothing required for a 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?

The tool takes no parameters, so there is nothing for the input schema to document and the baseline is 4. The description instead spends its words on output-field semantics (lag_hours, source_latest_known), which is a sensible use of the space.

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

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

The opening sentence states a specific verb and resource ('Return source import and extraction times from stored study results'), then names the sibling tool covering nearby territory (get_changes for record events, get_my_usage for quotas). An agent can distinguish this from all fourteen siblings 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?

Explicit when-to-use ('inspect data freshness') paired with two named alternatives and the condition that selects each ('record events', 'caller quotas'). This is exactly the routing information an agent needs given the crowded sibling set.

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 behavior, so the description only needs to add scope context — which it does by clarifying this reports account access rather than evidence coverage, a boundary an agent could easily confuse. It does not discuss windows' time basis or how grants relate to quotas, but the output schema carries the return shape.

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 resource list before routing guidance, and every sentence carries routing or scope information. The closing clause restates the account-vs-evidence boundary already implied by the sibling names, which is a small redundancy rather than waste.

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 parameterless, read-only inspection tool with a full output schema and complete annotations, the description covers everything needed to select and call it. Return-value details are correctly delegated to the output schema.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. Nothing in the text misleads 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?

Opens with a specific verb and enumerated resources (plan, grants, quotas, usage in current windows), so the agent knows exactly what account state is returned. It also explicitly distinguishes itself from get_freshness and get_changes, removing ambiguity among 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?

States the use case ('inspect access limits and remaining allowances') and names two concrete alternatives with the conditions that select them (source import times, record updates). No exclusions are 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?

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful interpretation beyond that: counts and key findings use administered findings only, a zero human count means no checked human findings within filters rather than no human study existing, and trial counts distinguish entries that test the peptide from entries that only mention it. Much of this concerns return-value semantics rather than invocation behavior, so it is strong but not fully invocation-focused.

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 purpose and sibling routing are front-loaded, but the description is a long paragraph with many output-detail sentences, including key_findings_v0.4 ordering, coverage.checked_years, coverage.search_scope_years, and evidence_summary.trials.other_registry_entries. Since an output schema exists, much of this is likely redundant with structured data, and the unexplained studied_doses reference adds ambiguity.

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 overview tool with an output schema, the description is more than complete. It covers intended use, alternatives, evidence-class interpretation, zero-count caveats, coverage fields, trial-counting semantics, and notices describing coverage limits. No critical invocation detail 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%, and the schema already defines peptide examples, the view enum, and the community grant requirement. The description never explains the view parameter or the community dataset grant behavior, and adds no syntax or format details beyond the schema's own descriptions. Baseline 3 is appropriate 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 states a specific verb and resource: 'Return a precomputed summary of one peptide' and enumerates identity, sequence, checked findings by evidence class, trials, key findings with citations, coverage, and notices. It also distinguishes this from siblings by directing unclear names to resolve_peptide, specific outcomes to search_findings, and multi-peptide comparisons to compare_peptides.

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 explicitly says 'Use this for an overview of a known peptide' and names the alternatives for adjacent use cases: resolve_peptide for an unclear name, search_findings for a specific outcome, and compare_peptides for 2 to 5 peptides. The dose-question pointer to studied_doses and get_community_practice adds another routing condition, though studied_doses is not a sibling tool and is left unexplained.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description adds the non-obvious temporal behavior that as_of_seq reads data as it stood at an earlier data_seq. It does not discuss result size, truncation, or rate limits, though the presence of an output schema reduces the need to describe return shape.

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?

Four tight sentences, front-loaded with capability then routing then the temporal parameter; every clause carries either a routing or a behavioral fact. Nothing is padded or repeated.

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 tool with full schema coverage, rich annotations and an output schema, nothing material is missing: the agent knows what it returns, which IDs work, when to prefer siblings, and how to time-travel. Return-value detail is correctly delegated to the output schema.

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 both parameters are already documented in the schema, and the description largely restates the same facts (accepted ID forms, as_of_seq for reproducing an earlier answer). It adds no syntax, precedence, or edge-case guidance beyond what structured data already provides, so the baseline of 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?

Opens with a specific verb and resource ('Return one full peptide, publication, finding or trial record') and enumerates the exact ID namespaces it accepts, so the agent knows precisely what entity set this covers. It is also clearly distinguishable from resolve_peptide and the search_* siblings, which are named 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 positive conditions ('known records or fields omitted from compact results') and names three alternatives with the condition that selects each: resolve_peptide for an unclear name, search_publications to find papers, replay_query to repeat a saved search. The when-not-to-use cases are explicit rather than inferred.

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 real context beyond that: the result is scoped to the first page and includes a result_set_hash the caller can compare. It stops short of describing what a hash mismatch actually signals (reproduced vs. diverged) or any pagination path past page one.

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 action and its distinguishing output come first, the intended use second, and the sibling routing last. Front-loaded and free of restatement.

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

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

An output schema exists, so return values needn't be explained, and annotations carry the safety and idempotency story. What remains thin is the boundary case: an agent doesn't learn whether non-identical results are returned normally or flagged, nor how to go beyond the first page.

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% — query_id documents its pattern and origin ('query_id from a search_response') and view documents its enum and default. The description adds no syntax or format detail about either parameter, which is the expected baseline when the schema does the work.

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 — return a saved search — and pins down the scope: original data_seq, first page only, plus a result_set_hash comparison. That verb/resource/scope triple is enough for an agent to distinguish it from search_findings and get_record 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 an explicit trigger ('check whether a recorded query reproduces identical data') and names two alternatives with the exact condition that selects each — search_findings with as_of_seq for a new earlier search, get_record with as_of_seq for a single earlier record. When-to-use, when-not-to-use, and substitutes are all present.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description goes well beyond that by disclosing the matching cascade (exact alias, normalized alias, trigram, edit distance), the normalization rules, the 2-error edit-distance cap restricted to featured peptides, and that trigram/edit-distance results are guesses. It also explains the ambiguous-status behavior, which is exactly the kind of outcome semantics an agent needs.

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?

Purpose and the sibling alternative are front-loaded, then matching details follow in a logical order. It is dense with short declarative sentences, though the normalization and edit-distance sentences could be tightened slightly without losing 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?

An output schema exists, so return values need not be described, and the description still covers the one non-obvious return case (ambiguous status yields candidates without a selection). For a single-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is already documented with an example, so the baseline is 3. The description adds real meaning beyond the schema by explaining what forms the 'name' accepts (alias, code, Greek-letter names, case/space/hyphen-insensitive) and how fuzzy input is tolerated.

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 ('Return peptide IDs and name matches for a name, alias or code') and explicitly distinguishes itself from the sibling search_peptides, which it names. An agent can tell the two apart 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 explicit when-to-use guidance ('Use this before other calls when the name is unclear') and names the alternative with the condition that selects it ('Use search_peptides instead to browse or filter many peptides'). Both the positive and negative cases are covered.

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

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

Annotations only cover read-only/idempotent safety, so the description carries the real behavioral burden and does: exact total_count, pagination semantics ('complete is true only on the last page'), retracted-source exclusion, and citation sourcing via included.publications. It also pre-empts a costly misreading — a zero human count means no checked human findings under those filters, not that no human study 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?

Front-loaded with what is returned and the sibling alternatives, then layered detail on evidence class and peptide role. A few sentences restate the same idea (evidence class enumerated twice, count-of-zero explained at length), but nearly every sentence carries operational meaning for a 20-parameter tool.

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 20-parameter, zero-required search tool with an output schema, the description still covers what matters: result envelope fields, pagination termination, default validation/retraction behavior, and the dose provenance. Nothing an agent needs to invoke it correctly or interpret an empty result 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; the description nonetheless adds interpretive meaning beyond the schema for filters such as peptide_role (administered vs endogenous_level, and why endogenous measurements are not evidence about taking the peptide) and outcome_group. It does not add much for q, sort, limit, cursor or the year bounds, which the schema already explains well.

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 ('Return checked findings with exact total_count and source sentences in included.passages') and clarifies the unit ('Each finding is one claim from one paper'). It explicitly distinguishes itself from search_publications and get_peptide_brief, so an agent can route 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?

Gives explicit routing guidance ('Use this for specific outcomes... Use search_publications instead for paper discovery, or get_peptide_brief for an overview') and names the filter dimensions. It also tells the agent which filter to apply for the common question type ('The peptide_role=administered filter selects studies that gave it').

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, openWorld, idempotent, and non-destructive, so safety is covered. The description adds genuinely useful semantics beyond that: results are live and unchecked, and carry a separate unchecked label, which tells the agent how to treat the output. It stops short of noting latency, rate limits, or that results may be incomplete relative to the indexed corpus.

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 core action, followed by routing guidance and then provenance semantics. Every sentence carries distinct information with no padding.

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

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

An output schema exists, so return values need not be explained. For a read-only, open-world search tool the description supplies purpose, routing, and result-provenance context — everything an agent needs to select and 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 q, limit, cursor, and peptide are all documented in the schema, including the cursor reuse instruction. The description adds no parameter-level detail beyond that, 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 ('Return live, unchecked papers') plus the upstream source ('from Europe PMC'), and immediately marks the results as unchecked. This lets an agent distinguish it from search_publications and search_findings 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 explicit when-to-use conditions ('gaps in database coverage or an explicit live literature search') and names two alternatives with the condition that selects each (stored papers → search_publications, checked claims → search_findings). Nothing 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine domain behavior beyond that: it defines where evidence_level and registry_level each come from and explicitly warns that a trial, phase or approval never raises evidence_level and that registry_level "says nothing about results" — exactly the trap an agent would fall into. It stops short of describing result shaping (view/compact behavior) or ordering semantics, which keeps it off a 5.

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 alternatives, then field semantics; no filler sentences. It is slightly redundant in re-explaining evidence_level and registry_level after the parameters, but each sentence still carries routing or disambiguation value.

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?

The tool has 10 optional parameters, an output schema and full annotation coverage, so the description needn't document returns or safety. It covers purpose, routing and the one conceptually subtle part of the filter surface, leaving nothing an agent needs in order 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 coverage is 100% and every one of the 10 parameters, including the enum values and the evidence/registry disambiguation, is already spelled out in the schema, so the description is largely restating it. It does usefully surface the evidence_level vs registry_level distinction at the top level, but adds no syntax, defaults or interaction rules the schema lacks — 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?

The opening sentence gives a specific verb and resource ("Return peptides with identity and evidence counts") and the rest names the two siblings it must be told apart from: resolve_peptide for a single unclear name and get_peptide_brief for a single summary. An agent can route correctly without opening any schema.

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

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

It states the browse/filter use case and enumerates the filter axes (text, category, kind, evidence level, registry level, curated launch list), then gives explicit exclusion routing to two named alternatives. This is the when/when-not/alternative pattern at full strength.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: the layer 1 vs layer 2 model, the contains_unchecked_papers flag on layer 2 results, and the licensing constraint on abstract text. It is capped at 3 because it never states pagination or result-size behavior, which is left entirely to 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?

Purpose and scope are front-loaded, then alternatives, then a compact glossary of result fields. Every sentence carries semantics, though the field glossary runs long enough that an agent skimming for invocation guidance must read past several result-oriented sentences.

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?

This is a broad, 14-parameter search tool with a rich output schema, yet the description still supplies the interpretive layer an agent needs to read results correctly: what extraction_status values mean, why design_hint is not a verified design, and when abstract text is absent. Nothing essential for correct invocation is omitted.

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 baseline is 3 and every parameter is already documented. The description adds interpretation rather than new parameter detail: it explains that extraction_status encodes layer membership and warns that design_hint is an unchecked PubMed tag while profile carries the checked-finding design. That is useful but does not extend to the 14 parameters individually.

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 first sentence names a specific verb and resource plus the two things it returns: stored papers with citation identifiers and extraction status. It immediately distinguishes itself from search_findings and get_peptide_brief by naming the alternative each time.

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 explicit when-to-use triggers (paper discovery, publication dates, unchecked coverage) and routes two competing needs to named siblings: checked claims and source sentences to search_findings, peptide overviews to get_peptide_brief. An agent has no inference left to do.

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 safety is covered. The description adds meaningful interpretive behavior beyond that: that registration alone is not evidence of an effect, that other_registry_entries flags non-trial links, that has_results means posted results, and the view=list paging ceiling of 100 rows. It does not cover rate limits or auth, but for a read-only search tool this is substantial added context.

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 core action, then sibling routing, then role semantics, then caveats — a sensible order with little waste. It is dense and runs long, and the 'other_registry_entries signals their presence' sentence is slightly cryptic out of context, but no sentence is redundant.

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

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

With 12 optional parameters, an output schema and rich annotations, the description supplies exactly the decision-level guidance an agent needs: sibling routing, default role behavior, what counts as a trial versus a mention, and result-status interpretation. Remaining details (sort enums, phase values, cursor mechanics) are fully documented in the schema and need not be repeated.

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 the default role=tests semantics, what measures/mentions actually mean in registry terms, and the list-view page limit. The role explanation in particular adds interpretive meaning (a measures link is not a trial of taking the peptide) that the schema's terse enum text does not convey as forcefully.

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 (return registered clinical trials) and names the exact fields returned: registry status, phase, posted-results status and peptide role. It also names the two siblings it is not (search_findings, get_record), so an agent can route 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 says when to use this tool versus search_findings (checked study results) and get_record (one full trial). It also spells out when to pick each role value and warns that role=measures/mentions return entries that 'are not trials of taking the peptide', which is the key selection nuance.

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