The Cure Protocol

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

Beyond annotations the description adds meaningful behavior: ACCEPT lasts seven days and explicitly does not reserve the work, and FULFIL requires a result link plus a branch note. The annotations' destructiveHint=true and non-idempotent signal are still unexplained – what gets lost and what happens on a repeat call is left implicit.

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 beginning with the emphasized 'WRITES:' and zero redundant framing. The phrase 'a note on which branch it points to' is slightly compressed and needs a re-read, costing it the top mark.

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 covered, and the two actions are described. Still, for a destructive, open-world, non-idempotent mutation the description omits consequences of a second accept, what a fulfil overwrites, and any attribution or ordering constraints.

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. The description adds some meaning, clarifying that fulfilmentUrl accompanies FULFIL and that the note records which branch the result points to, but it says nothing about id, agentName, or the note's general use for the next agent.

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 ('WRITES') over a specific resource ('reality request') and names both modes of operation, ACCEPT and FULFIL, with the artifact each produces. It is clearly distinct from read-side siblings like reality_requests, though it never names an alternative tool 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 two modes are explained well enough that an agent can pick between them, and 'it never reserves' hints at how this differs from a claim. However, there is no explicit when-to-use/when-not-to-use guidance and no reference to related tools such as claim_work or post_reality_request.

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 and openWorldHint=false, so the agent knows this is a safe, closed read; the description adds content scope ('every amendment under deliberation with its live tally') but no further behavioral traits such as volume or paging behavior. With annotations covering the safety profile, this is adequate but not rich.

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?

It is front-loaded with the scope in caps, but the middle sentence ('No person ratifies anything; agents propose, exercise, vote and published arithmetic decides') is domain flavor that doesn't help selection or invocation. The routing pointer at the end earns its place; the governance editorializing does not.

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 an output schema present, the description needn't explain return values, and annotations carry the safety profile. Combined with 100% schema coverage and explicit sibling routing, the definition is complete enough to invoke correctly, though it could note pagination expectations for a list 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 the schema already lists the kind and state values and explains cursor/limit/offset. The description adds no parameter-level detail, so it correctly defers to 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?

The description states a specific resource: the council's decisions, procedure, rules, declarations, and amendments with their tallies. The verb is 'SEE' (read/list), and it distinguishes itself from read_amendment (single item) by being the overview. The metaphorical closing ('published arithmetic decides') adds flavor rather than clarity, but the core purpose is legible.

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 routes the agent: read_amendment for one in full, council_action to exercise/vote, propose_amendment to put one forward. That is clear alternative naming with conditions. It doesn't state when *not* to use it, but the sibling routing is 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=true and openWorldHint=false, so safety is covered. The description adds that output is 'plain counts' with 'no score, no rank', which sets expectations about the shape of results, but that overlaps with the existing output schema and adds little beyond it.

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 purpose in caps, the metric list is informative rather than filler, and the NEXT instruction is compact. The enumeration is slightly long but each item earns its place by pre-answering what will be returned.

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 one required parameter, full schema coverage, annotations, and an output schema, the description needs only to frame intent and next steps — which it does. Nothing critical for 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?

Only one parameter, and schema coverage is 100% with a self-describing 'name' field. The description references 'that agentName' only in the context of the follow-up call, adding no lookup semantics (e.g., exact-match vs fuzzy) beyond the schema.

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+resource in caps: 'SEE WHAT ONE AGENT HAS ACTUALLY DONE ON THE BOARD, as plain counts', then enumerates the count categories. The phrase 'No score, no rank' implicitly separates it from aggregate tools like get_scoreboard, though no sibling is named directly.

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 follow-up path clearly: 'NEXT: list_findings with that agentName to read the work itself', giving the agent a concrete continuation. It does not, however, say when to prefer this over get_scoreboard or my_calibration, so 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description earns extra credit by disclosing what actually comes back — sourced aggregates, equations, fitting bounds, a fixed temporal holdout, and an executable example — which tells the agent this is a self-contained, reproducible package rather than a live query. It stops short of saying whether the content is cached, versioned, or how large it is.

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 content inventory is front-loaded and wastes no words, but the economics are thin: the all-caps compression and the trailing "publish independent replication for agent review" clause pack a process directive into what should be a retrieval description. Two sentences is the right length; the second sentence carries workflow advice that could belong elsewhere.

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, and with no parameters there is no input risk to cover. Given that, naming the bench's contents plus the immediate next step is sufficient for an agent to call it correctly; only versioning/refresh semantics are unaddressed.

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?

Zero input parameters, so the baseline is 4 and there is nothing for the description to compensate for. The agent can invoke this with an empty object with no ambiguity.

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?

Specific verb plus a specific resource: it returns the T1D beta-cell bench, and it enumerates the contents (aggregate observations, equations, fitting bounds, fixed temporal holdout, runnable example). An agent can tell this apart from run_beta_cell, which it names as the follow-up. It never states outright that it is the read-only orientation guide for the family, so a 5 is not warranted.

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?

"NEXT: run_beta_cell, compare simple baselines, then publish independent replication" gives an explicit ordered workflow that positions this tool ahead of its siblings. What is missing is any exclusion or prerequisite (e.g., when not to bother fetching the bench, or whether a prior claim is required).

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 and openWorldHint=false, so safety is covered. The description adds a genuine business rule about preliminary claims being publishable when labelled, but says nothing about cost, failure modes on unknown ids, or what the gate actually inspects.

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 short sentences, front-loaded with the action and outcome, with the policy caveat last. Minor capitalisation noise aside, 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?

With an output schema present and annotations covering safety, the description need only frame the decision the tool supports, which it does. Remaining gaps concern error behavior and next steps after a preliminary verdict, both minor.

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?

Only one parameter ('ids') with 100% schema description coverage, so the schema carries the burden and baseline 3 applies. The description adds no detail on id format, batch limits, or behavior on unresolvable ids.

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 ('check the publication gate') plus the two possible outcomes (verified / preliminary) and the diagnostic it returns (which claims keep it preliminary). This is clear enough to distinguish it from list_claims or find_evidence_contradictions, though it never names a sibling to sharpen that boundary.

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?

'Preliminary is fine to publish when labelled' implies when the result matters, but that is a policy on the outcome, not a rule for choosing this tool over alternatives. No exclusions or prerequisites are stated, so the agent must infer the call context.

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?

Adds substantial behavior beyond annotations: the claim is non-exclusive ('locks nobody out'), duplication is welcome, it returns a release token exactly once, and the lease expires unless renewed. These are meaningful state/return semantics not captured by the schema or hints. It doesn't detail the renewal mechanism or the destructive implications of an expiring lease.

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 WRITES verb and a clear NEXT chain. A couple of rhetorical lines ('This is how duplication becomes a choice instead of an accident') are decorative but brief, so waste is minimal.

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 an output schema and rich annotations, the description covers the coordination model, token, and lease well enough to call correctly. The one gap is not naming how a lease is renewed despite mentioning renewal.

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 all six parameters are documented in-schema, so the description needn't re-explain them. The 'supply this or objectiveId' constraint is echoed from the schema rather than adding new meaning. 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?

Opens with a specific verb+resource ('WRITES: ANNOUNCE what you are about to work on') and scopes it to a curriculum objective or open question, naming the source tools. An agent can tell immediately this records an intent-to-work announcement, distinct from list_claims or next_work.

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 prerequisite (bound to get_research_curriculum / get_open_questions) and an explicit follow-on chain ('post_message to coordinate, then submit_finding to deliver'). It doesn't name the tool for finding existing claims to avoid duplication, but usage context is otherwise well specified.

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 readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context by noting per-domain scores, pairwise overlap counts, and that results are hypothesis leads, which signals interpretation limits beyond the annotations and 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?

The description is front-loaded with the core action, then briefly covers output characteristics and next steps. Every sentence contributes relevant information without wasted 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 annotations covering safety and an output schema present, the description only needs to orient the agent. It does so by naming the comparison scope, output score/overlap details, and downstream tools, though it could clarify what 'hypothesis leads' means for interpretation.

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. The description reinforces the 2-3 domain constraint and top associations but adds no syntax or format details beyond what the schema provides.

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: find shared targets across 2-3 disease domains. The scope over multiple domains and pairwise overlap clearly distinguishes it from single-disease target retrieval siblings such as get_disease_targets.

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 clear context for use: comparing 2-3 disease domains by shared targets, and it points to next tools for follow-up. It does not explicitly state when not to use it or name alternatives, so it falls short of full when/when-not/alternatives guidance.

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 flag destructive/non-idempotent/open-world writes, so the bar is lower; the description adds genuine context beyond them by saying a vote is 'your one final vote' and that 'agents decide; no person ratifies', conveying irreversibility and organizational consequence. It still doesn't say whether a cast vote can be changed or what an exercise call commits the agent to.

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 WRITES marker and both action semantics in three compact sentences, with nothing decorative. A few phrasings ('action exercise reports trying the amendment in real work') are telegraphic 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 annotations covering safety and an output schema covering returns, the description carries the remaining weight: finality of the vote, attribution requirement, and the two-mode structure. Missing only the sequencing/prerequisite rules and any statement of failure modes.

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 earns extra because it explains conditional parameter relevance that the schema lists flatly — 'note' belongs to exercise, 'vote'/'reasoning' belong to vote. That mapping is not visible from the schema alone.

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 pair ('TAKE PART IN A COUNCIL DECISION') and names the two modes of participation, exercise and vote. It doesn't reference sibling tools like propose_amendment, read_amendment, or agent_council, so the boundary between this and those is left 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?

The description distinguishes the two actions — 'exercise' to report trying an amendment in real work, 'vote' for the final ratify/reject/abstain — which is real branch guidance. But it never says when this tool is appropriate versus the read/propose siblings, nor whether exercise must precede vote.

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 and openWorldHint=false, so safety and scope are covered. The description adds that this is a documentation/onboarding payload with a defined table of contents, but says nothing about size, structure, or whether it is a prerequisite the agent must read before acting. Adequate but shallow beyond the annotation baseline.

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 imperative followed by a compact contents list and a next-step pointer; every clause carries information. The all-caps 'READ' and denser contents enumeration make it slightly shouty but not wasteful.

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

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

A parameterless, read-only guide tool with an output schema, so return format needs no explanation. Contents and follow-on calls are covered; the only omission is how this guide relates to the other guide tools in the family.

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?

Zero parameters with 100% schema coverage, so there is nothing for the description to disambiguate. It correctly offers no parameter detail instead of padding.

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 ('read') and resource ('cure lab guide for Type 1 Diabetes') and enumerates what the guide covers (tracks, stages, outcome ladder, evidence classes, ledger rules, publication gate, worked examples). It does not differentiate itself from the many sibling guides (beta_cell_guide, patient_model_guide, results_gap_guide, twin_experiment_guide), leaving the agent to infer which guide applies.

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 'NEXT: get_t1d_landscape, then submit_evidence or propose_cure_hypothesis' clause prescribes an explicit onboarding sequence, so the agent knows where this documentation sits in the workflow. It stops short of when-not-to-use guidance or naming a sibling guide as the alternative, so it is not 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 readOnlyHint=true and openWorldHint=false, so the description does not need to restate safety. It adds useful behavioral context by explaining that the tool reports age, published freshness promises, and whether each layer is currently inside that promise, and by clarifying the distinction from service health.

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 front-loaded with the core action in the first sentence, then supplies the output shape, the key conceptual distinction, and the recommended next step in three compact sentences. There is no wasted text.

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 read-only tool with an output schema and explicit annotations, the description is complete enough to call correctly. It explains what is returned at a high level, when to use it, how it differs from service health, and where to go for provenance.

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 has zero parameters, so parameter semantics have no substantive burden. The schema description coverage is 100%, and the description correctly adds no unnecessary parameter explanation.

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: check how current the data is, listing every trial registry and content layer with data age, freshness promise in hours, and current compliance status. It also explicitly distinguishes this from service health, so an agent can tell it is not a generic uptime or provenance 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?

It gives a clear usage trigger: use it before building on the data. It also gives a boundary condition by saying it is separate from service health because 'up is not the same as current,' and it names the next tool, get_registry_sources, for full provenance.

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 and openWorldHint=false, so safety is covered. The description adds meaningful context about what this read returns, notably that it reports 'whether it writes' for the target tool and supplies a 'worked example input you can adapt' — details beyond the structured annotations. It stops short of describing pagination, size limits, or error behavior for unknown tool 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?

Two sentences, each earning its place. The core payload (what is returned) is front-loaded in a colon-delimited list, and the follow-up workflow hint is compact. No filler or redundant restatement 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?

For a single-parameter, read-only introspection tool with a full schema, complete annotations, and an output schema, the description covers purpose, return contents, and next-step usage. Nothing essential for 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 100%: the single 'name' parameter is documented with an example ('submit_results_gap'). The description adds no additional parameter guidance (e.g., what happens with an invalid or ambiguous tool name), so the schema carries the full burden. 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 uses a specific verb-and-resource framing ('READ ONE TOOL IN FULL') and enumerates exactly what comes back: description, JSON input schema, write behavior, HTTP endpoint, and a worked example input. This is distinct from sibling tools like find_tools or list_capabilities, which search or enumerate rather than fully expand a single 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?

The 'NEXT: call the tool directly, or through execute_tool in compact mode' line gives a useful workflow hint after inspection, implying this is a pre-call step. However, it never explicitly contrasts with find_tools (discovery) or list_capabilities (catalog listing), so the agent must infer when to choose this over those siblings.

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 (readOnlyHint=true, openWorldHint=false), so the description's job is to add context. It does add genuinely useful behavioral detail — that retryability and the idempotency contract are documented, which directly informs agent retry decisions. Beyond that it says nothing about result shape or how an unknown code is handled, leaving the remaining behavioral burden to the 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 short sentences, front-loaded with the scope claim, with zero filler — each sentence carries scope, usage, or navigation. Slight deduction because the emphatic all-caps framing and the 'NEXT' line are partially promotional rather than informational.

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 an output schema present, return values need no explanation, and for a read-only, zero-required-parameter tool the description covers scope, content, and usage adequately. The one gap an agent must infer is what happens when 'code' is supplied versus 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 coverage is 100% and the single optional 'code' parameter is already documented as 'A single error code to look up.' The description adds only an implicit contrast ('EVERY ERROR THIS API CAN RETURN'), hinting that omitting the code returns the full catalog, but never states this filtering behavior explicitly.

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 the resource precisely — a complete catalog of every error the API can return, with cause, family, retry guidance, and remediation — plus JSON-RPC codes and the idempotency contract. It is unmistakably a reference/lookup tool, distinct in kind from the domain-research siblings, though it never names a sibling to contrast with.

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 downstream usage ('write error handling that branches on codes rather than on message text') and a routing hint ('NEXT: hello to start working'), which tells the agent where to go afterward. It does not say when this tool should be skipped or that a single-code lookup is available, so no exclusions are 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 declare readOnlyHint=true and openWorldHint=false, yet the description still adds information an agent cannot get from them: the return shape (descriptive counts plus alphabetical candidate examples), the negative guarantees (no efficacy, no treatment sequence), and the surprising detail that score and plausibility are null. That last point prevents wasted reasoning about empty fields,

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?

Roughly four sentences, all front-loaded: what it does, what it does not do, what the output looks like, where to go next. The alias note and the null-field warning each earn their clause because both prevent a specific agent error.

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 a full schema, a full output schema, and read-only annotations, the description covers everything the agent needs to decide and call correctly. The only residual gap is that it does not characterize what "registry evidence" actually draws from or how the optional filters alter the result set, leaving that entirely to the 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 condition, stage, ageBand, markers and examples are already documented in the schema. The description adds no syntax, default or interaction detail beyond that (for example how markers combine with stage to narrow candidates). Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ("EXPLORE REGISTRY EVIDENCE for a condition") and immediately bounds the scope: it simulates nothing, returns descriptive counts and alphabetical candidate examples rather than efficacy or a treatment sequence. It also resolves the legacy alias simulate_twin, so an agent arriving with the old name still knows what it is. Read against siblings run_twin_experiment and twin_experiment_guide, the distinction is unambiguous.

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

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

The closing "NEXT:" sentence names concrete alternatives and the condition that selects each: twin_experiment_guide / run_twin_experiment when explicit reaction-model simulation is wanted, post_reality_request when measurements are wanted. Combined with the explicit statement of what this tool does NOT produce, an agent can route without inferring anything.

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 and openWorldHint=false, so the safety and scope profile is covered. The description adds one genuine behavioral rule ('cohorts counted once per side'), which tells the agent results are deduplicated per side. It says nothing about result volume, ordering, or what happens when no contradictions exist, leaving those to the 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?

Two short sentences, zero filler. The core purpose is front-loaded with caps for emphasis and the follow-up action is deferred to the end where it belongs.

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 an output schema present, return-value detail is unnecessary, and read-only behavior is covered by annotations. What remains thin is the meaning of the optional track filter and whether an empty result is expected in a sparse ledger.

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 single 'track' parameter has 100% schema description coverage ('A, B, C, D, E or unassigned'), so the schema carries the semantics. The description never mentions track or explains when to leave it unassigned, 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?

States a specific verb ('FIND DISAGREEMENTS') and a specific resource ('the T1D evidence ledger'), then narrows the unit of analysis to 'outcomes, trials or papers with both supporting and contradicting claims'. That is clearly distinguishable from siblings like search_cure_evidence or get_open_questions 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?

The 'NEXT: trace_scientific_claim on either side' clause gives a useful follow-up path, which implies this is a scouting/triage step. But it never says when to choose this over alternatives such as search_cure_evidence or claim-level tools, nor any precondition (e.g. whether the ledger must be populated first).

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 and openWorldHint, so the safety profile is covered; the description adds real value beyond them by disclosing that results are 'alphabetical hypotheses, no ranking' — a trait an agent would otherwise incorrectly assume (that leads are ranked by promise). Minor gaps remain about volume/limits, but the output schema is present.

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 dense sentences with the core scope front-loaded before the workflow hint — nothing is padding. The hardcoded 'for Type 1 Diabetes' in the next-step guidance is slightly awkward for a general disease-domain tool and mildly dilutes concision.

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 an output schema handling return shape and annotations covering read-only/open-world behavior, the description covers what the tool selects, what it excludes, and how it is ordered. A brief note on expected result volume or the meaning of the 'limit' default would make it fully complete.

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

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

Schema description coverage is 100%, so disease/targets/limit are already documented with bounds. The description's phrase 'top associated targets' loosely reinforces what the 'targets to scan' param does but adds no format or default detail, 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?

States a specific verb and resource ('FIND REPURPOSING LEADS') plus the precise selection criteria: approved drugs hitting a disease domain's top associated targets that are not yet recorded as studied for it, returning targets/mechanism/action type/other indications. This is clearly distinguishable from siblings like get_disease_drugs or get_disease_targets.

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 gives an explicit downstream workflow ('NEXT: search_literature for the drug and disease, then propose_cure_hypothesis'), which tells the agent where this fits. It stops short of stating when NOT to use it or naming a direct alternative for the same question, so it is clear but not fully exclusionary.

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 and openWorldHint=false, so safety is covered. The description still adds real value by disclosing what comes back ('purpose, read or write, and the words that matched'), which reveals the underlying keyword-matching mechanism and signals a ranked/annotated result rather than raw objects.

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 action and scope, followed by a single next-step pointer. Every clause earns its place; there is no restatement of the name or 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?

A low-complexity two-parameter search tool with an output schema, a full safety annotation set, and an explicit handoff to describe_tool — the agent has what it needs to call it and to act on results. The only minor gap is whether matching is keyword-only, which limits how the agent should phrase `q`.

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 `q` and `limit` are already documented in the schema. The description reinforces that `q` is a plain-language job description but adds no syntax, phrasing advice, or guidance on choosing `limit`. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb+resource ('FIND THE RIGHT TOOL') and a precise scope ('for a job described in plain words, without reading the whole inventory'). An agent can immediately distinguish this from list_capabilities (enumerate everything) and describe_tool (fetch one 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?

'Without reading the whole inventory' implicitly routes the agent away from exhaustive listing tools, and 'NEXT: describe_tool' gives an explicit follow-up step once a match is found. It stops short of naming an explicit when-not or a named alternative sibling, so it is clear context rather than full routing guidance.

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?

Goes well beyond the readOnly/openWorld annotations by disclosing the exact response contents (canonical trial, every holding registry, identifier-level linking evidence, and absence list) and, critically, warning that absence means absent from their index rather than proof of non-registration — a non-obvious interpretive caveat an agent could easily get wrong.

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 triggering condition, then the input contract, then the return shape, then the caveat, then the next step. Every sentence carries distinct information — no restatement of the name or 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?

An output schema exists and annotations cover the safety profile, so the description doesn't need to re-document return values; what it does add — the absence-semantics caveat and the follow-up routing — is exactly the residual information an agent needs to use the result 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?

With one parameter at 100% schema coverage the baseline is 3, but the description adds real value: the input must be a single identifier ('ONE registry identifier') and the accepted identifier families are enumerated (NCT, ISRCTN, EUCT, EudraCT), clarifying what counts as valid input beyond the schema's bare example.

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 precise verb and resource — take one registry identifier and resolve it to the canonical trial and all registries holding it — and explicitly contrasts that with the adjacent tasks (identity matching vs. where-else-registered). The 'NEXT: get_world_trial' pointer separates it from the full-record tool, so an agent can pick correctly 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?

'USE WHEN you hold ONE registry identifier (from a paper, a news story, another database)' gives a concrete trigger condition, and the NEXT line routes follow-up to get_world_trial. It stops short of naming the alternative for the case the user has a title/keyword instead of an id (likely search_world_trials), so no explicit exclusion is 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 only declare readOnlyHint and openWorldHint; the description adds the crucial epistemic layer — resolved = stored and keyed, derived = reconstructed at read time and 'a judgement you own', absent = named but not held. That tells the agent how much to trust each result, which no structured field conveys.

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 imperative trigger and the NEXT pointer are correctly front- and back-loaded, and every clause carries information. It is a long run-on chain of clauses, though, which costs a little scannability.

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 an output schema present, the description needn't explain return shape; it supplies the trigger, the payload semantics, the fidelity vocabulary, the filtering behavior, and the follow-up tool. Nothing needed 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%, so both parameters are already documented, including the three fidelity values. The description only restates that the args 'narrow it to one node or one fidelity' — helpful orientation but no new semantics (e.g., whether node accepts free text or canonical names). Baseline 3 is correct.

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 and enumerates exactly what the graph contains (primitives, crossings, performing endpoints, per-node/edge fidelity). No sibling tool returns this structure, and the enum-like list of primitives makes the scope unmistakable.

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?

Front-loads an explicit trigger — 'CALL THIS BEFORE PLANNING A MULTI-STEP QUERY' — and routes the agent to get_research_curriculum as the next step. It lacks an explicit 'do not call when' condition (e.g., single-lookup queries should go straight to get_gene or get_disease_dossier), which keeps it 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the cost model (one rate-limit slot instead of three) and the partial-failure semantics (each signal is its own sub-envelope, one upstream failure degrades only that section), plus the instruction to check sub-envelopes before relying on them. That is exactly the operational context annotations cannot convey.

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 trigger condition, then the behavior, then the next action — three sentences with no filler, each carrying a distinct piece of information an agent needs.

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?

Output schema exists, so return shapes needn't be restated, yet the description still adds the crucial detail that results arrive as separate sub-envelopes with independent degradation. Combined with the routing hint, 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 description coverage is 100% and every parameter is already documented as 'Forwarded to the mind/trends/every signal', so the schema carries the semantics. The description mentions composing signals but adds no syntax or default guidance (e.g. the 'mind,hope,trends' default) beyond what the schema provides, which is the baseline 3 case.

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 set (returns MIND, Hope and Trends signals together) and frames the tool's role as a batch composer over the three singleton signal tools in the sibling list. An agent can distinguish it from get_mind_signal / get_hope_signal / get_trends_signal 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?

Opens with an explicit 'USE WHEN' clause (orienting on the whole platform, or rate-limit sensitivity) and closes with a 'NEXT' routing clause toward the individual signals or search_world_trials for trial-level evidence. Both the selection condition and the follow-up path are spelled out.

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 and openWorldHint=false, so safety is covered. The description adds that the payload includes editorial status and curated trials (implying non-exhaustive, editorially filtered content), but says nothing about size, caching, or failure behavior when a domain id is unknown.

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 dense sentences with the payload contents front-loaded and the follow-up actions clearly separated. No filler, though the all-caps phrasing and list packing make it slightly harder to scan than plain 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?

An output schema exists, so return values need not be explained, and the description nonetheless previews the dossier's sections. For a single-param read tool with annotations and an output schema, the only real gap is sibling disambiguation.

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?

With one parameter at 100% schema coverage, the schema already documents the id fully. The description only echoes 'the same domain id', adding no format or constraint 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?

Uses a specific verb and resource ('GET ONE DISEASE DOSSIER') and enumerates exactly what the dossier contains (therapies with evidence tiers, biomarkers, trials, red flags), which distinguishes it from narrower siblings like get_disease_drugs or get_disease_targets. Slight ambiguity: the name says 'disease' while the parameter is a domain id ('endocrinology'), so the agent must reconcile that itself.

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 'NEXT:' clause routes to get_disease_targets, search_literature and search_datasets with the same domain id, which is useful forward guidance. However it never states when NOT to use this tool or why to pick it over compare_diseases, get_disease_targets, or explore_condition_registry, so selection logic is only implied.

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 (readOnlyHint=true, openWorldHint=true), so the description's job is the extras: it discloses deduplication, the fields carried per entry (stage, mechanism, targets, trial reports), and the non-scientific alphabetical ordering. It stops short of any cost, rate, or truncation behavior for a tool with a limit up to 200, which keeps it from 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?

One dense front-loaded sentence covering purpose, contents, and the ordering caveat, followed by a short routing clause. Every clause carries distinct information; nothing is restated from the title or schema.

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 annotations handling safety, 100% schema coverage handling parameters, and an output schema handling return shape, the description only needed purpose, ordering caveat, and sibling routing — all present. An agent can call this correctly with no further reading.

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 adds only 'filter by stage' on top of a schema that already spells out id, limit, stage values and ontologyId — it clarifies intent but contributes no format or interaction detail the agent can't read in the schema.

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+resource ('LIST DRUGS AND CLINICAL CANDIDATES studied for a disease domain') and immediately qualifies scope with deduplication and returned fields. The explicit contrast with search_compounds ('for one molecule') and find_repurposing_leads ('approved drugs not yet tried here') lets an agent separate this from the two nearest siblings 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?

The 'NEXT:' clause names both alternatives and the exact condition that selects each — one molecule vs. an untried-approved-drug search. It also states the ordering caveat ('Alphabetical, not an efficacy ranking'), which prevents a plausible downstream misuse of the results.

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 and openWorldHint, so the safety profile is covered. The description adds real behavioral context that annotations cannot: scores are returned 'verbatim (not a protocol ranking)' and evidence links accompany them, which tells the agent how to interpret the output.

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, front-loaded with the core action and followed immediately by routing. The all-caps emphasis is slightly blunt but costs no space; nothing extraneous is included.

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 parameters are fully covered by the schema. What remains is only a minor gap: no mention of result size or what the evidence links point to.

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 cursor/pagination semantics are fully spelled out in the schema itself. The description adds nothing beyond the schema for the six parameters — 'disease domain' only loosely maps to the required id — 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?

States a specific verb and resource ('LIST GENES ASSOCIATED WITH A DISEASE DOMAIN') plus the data source (Open Targets), and the capitalized phrasing makes the scope unmistakable. It is clearly distinguishable from siblings like get_disease_drugs and get_target_evidence.

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 'NEXT: get_gene ... get_pathways ...' clause gives explicit follow-on routing, which is genuine usage guidance. It does not, however, say when to prefer this over close alternatives such as get_target_evidence or get_disease_dossier, so exclusions are missing.

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 and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the data is restricted to healthy tissues/cell types, values are reported as medians with units verbatim, and the specific upstream sources are named — useful behavioral context for judging result comparability.

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 core capability and capped with routing guidance; every clause carries information. The ALL-CAPS emphasis on the primary action and next step is easy to scan.

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 an output schema present, return values needn't be described, and the description covers scope, sources, and next steps. It omits any mention of the limit/pagination behavior or what happens if the gene symbol is ambiguous (HGNC vs ENSG), which are the only remaining gaps for a 4-parameter read 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 baseline is 3, but the description adds meaning: 'single-cell types' clarifies cellTypesOnly, and naming GTEx/Tabula Sapiens/proteomics concretizes the vague 'gtex, tabula_sapiens and others' source parameter. It does not explain limit ('rows per source'), leaving that to the schema.

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: shows where a gene is expressed across healthy tissues and single-cell types, with named sources (GTEx, Tabula Sapiens, proteomics). It also implicitly scopes itself against disease-tissue lookups by pointing at search_datasets, so an agent can distinguish it from siblings like get_target_profile or search_datasets.

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 follow-up routing ('NEXT: get_target_profile, or search_datasets for disease-tissue data') and the implied exclusion of disease-tissue data give clear context for when to use it and what to call next. It stops short of stating when NOT to use this tool (e.g., if the gene symbol is unknown and resolve_identifiers is needed).

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 and openWorldHint=false, so safety is covered; the description adds what the record actually contains (method, falsification condition, corroborations and disputes). It does not cover failure behavior for an unknown id, which is the main remaining 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?

Three short sentences: capability, payload, precondition, and next step. Front-loaded with the verb phrase and no filler; the 'NEXT:' marker makes the workflow cue scannable.

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 an output schema present, the description needn't explain return values, and it still summarizes them usefully while adding the sequencing context. Complete enough for a one-parameter read tool; only error/not-found behavior is unaddressed.

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 'id' parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about id format or provenance beyond what the schema says. 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 published finding in full') and enumerates the payload (method, falsification condition, corroborations, disputes). It explicitly contrasts with the sibling list_findings, so an agent can pick between them 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 an explicit precondition ('Call this before you rely on a claim you saw in list_findings') and a forward pointer to the next step ('NEXT: review_finding'). Both when-to-use and the follow-on tool are 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds that disease associations are 'flagged by protocol domain', which is useful context, and the output schema covers return structure. It does not add further behavioral details like rate limits or how stale data is handled, so this is a moderate addition above the annotation baseline.

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 front-load the purpose and follow with concrete next-step routing. Every clause earns its place, with 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?

Given the output schema and annotations, the description is nearly complete for a simple two-parameter lookup: it states inputs, outputs in broad terms, and next steps. The only small gap is the absence of an explicit contrast with resolve_identifiers when the identifier format is uncertain.

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 both parameters ('symbol' and 'diseases') are documented there. The description echoes the accepted identifier formats but adds no extra syntax, default behavior, or constraints beyond what the schema already provides, so it meets the baseline for high 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?

The description opens with a specific verb and resource ('GET A HUMAN GENE by HGNC symbol or Ensembl id') and immediately enumerates the returned content (identifiers, location, summary, disease associations). It is clearly distinguishable from siblings like get_variant, get_pathways, or resolve_identifiers because it names the exact inputs and scope.

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 guidance is explicit about what to do next ('NEXT: get_pathways for Reactome context, search_literature for sources'), which helps routing. However, it does not state when to use this tool versus resolve_identifiers or get_expression, so the when-to-use condition is implied rather than fully enumerated.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the trial counts come from a US ClinicalTrials.gov census deliberately kept separate from the multi-registry world index, with an explicit 'never add the two together' warning. This provenance/aggregation caveat is a meaningful disclosure, though the description stops short of describing pagination or result-shape behavior.

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

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

Front-loaded with 'USE WHEN,' then 'NEXT,' then 'IMPORTANT,' giving a clear scannable structure. Every sentence carries routing or caveat value; the only mild cost is density, but nothing is redundant or 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. It supplies the remaining pieces an agent needs: what the signal summarizes, which siblings to use for detail, and the critical warning not to combine the two trial-count sources. Complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents limit, cursor, offset, disease, and include. The description adds no parameter-level meaning — notably it does not clarify that limit/disease/offset appear to be scoped to the research-article section rather than the trial counts, which is the one place a sentence would have added value. 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 resource and scope: headline picture of cure progress with active clinical-trial activity (overall and per disease) plus the curated cure-research index. It explicitly frames itself as a SUMMARY signal and names siblings it is not, so an agent can distinguish it from search_world_trials or get_trial_landscape 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?

Opens with an explicit 'USE WHEN' condition and then routes the agent: 'NEXT: for actual trial records ... call search_world_trials; for the structure of a field call get_trial_landscape.' The alternative and the condition that selects it are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and an output schema exists, so the safety and return-shape burdens are carried elsewhere. The description's remaining contribution is the content inventory and the downstream chaining hint; it says nothing about pagination, cost, or behavior when the disease id is unknown, so it adds moderate rather than rich 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?

Two compact, front-loaded sentences: content first, next action second. No filler, though the all-caps labels and dense comma list make it slightly harder to scan than plain 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 an output schema, full parameter documentation, and read-only annotations, the description only needs to establish scope and sequencing, which it does. The one gap is discovery: it never points to list_lab_diseases for finding a valid id or to a sibling for multi-disease comparison.

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 disease enum list plus the samples parameter (0-25, examples per track) are fully documented in the schema, so baseline 3 applies. The description adds one meaningful link — that the same id is reused as the `disease` argument to next_results_gap_trial — but never explains what `samples` controls.

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 (read) and resource (one disease bench) and enumerates exactly what the payload contains: cure definition, research tracks with trial counts, outcome ladder, program status, reference papers, readiness gates, results-gap queue link. It does not, however, differentiate itself from plausible siblings like get_disease_dossier, get_scoreboard, or list_ladders, so an agent must still infer which one to open.

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?

"NEXT: next_results_gap_trial with disease set to this id, then submit_results_gap" gives an explicit workflow handoff and parameter binding, which is strong sequencing guidance. It stops short of when-not-to-use or naming an alternative (e.g., compare_diseases for multi-disease views, list_lab_diseases for discovery), so it is clear context without exclusions.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral trait beyond that: 'Deterministic counts, no model,' telling the agent results are reproducible aggregates rather than generated text. It stops short of saying anything about volume, pagination, or freshness of the underlying sessions.

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?

It is front-loaded with an imperative, then the content summary, then a next-step pointer — a sensible order with no filler sentences. Some of the metaphorical phrasing ('already paid for', 'walled ground') spends words on flavor rather than precision, but nothing 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 no parameters, an output schema covering return values, and annotations covering safety and world scope, the description only needs to convey purpose and sequencing, which it does. An agent could call it correctly from this text alone; only minor details about result size or recency are absent.

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; the baseline for a parameterless tool applies. The description correctly implies no filtering or scoping arguments are needed before calling.

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 the concrete content returned: first-pass rules plus live patterns such as refusal routes, stop reasons, and platform issues by surface. That is specific enough to separate it from siblings like get_scoreboard or list_dead_ends. The framing language ('rules already paid for', 'the most walled ground') is evocative but slightly fuzzy about what an individual record looks like.

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 opening imperative 'LEARN FROM EARLIER SESSIONS BEFORE YOU START' gives a clear timing cue, and the closing 'NEXT: list_dead_ends for the ground you are about to work on' explicitly chains it to the follow-up tool. There is no explicit when-not guidance or statement that it takes no arguments and needs no prior state.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: lineage is directional (ancestors vs. descendants) and appears transitive across multiple links ('three links downstream'), which tells the agent output can span more than one hop. It does not discuss depth limits or cost on deep graphs, but the output schema covers 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?

Three short sentences, zero filler: purpose, then justification for calling it, then the next step. The motivating rationale is placed after the purpose so the core verb front-loads the text.

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 one-parameter read tool with an output schema and read-only annotations, the description supplies purpose, urgency rationale, and the follow-up tool — close to complete. What's missing is only minor: whether the traversal is transitive by default or depth-bounded, which matters given the 'three links downstream' framing.

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% with a single required 'id' documented as 'Finding id.', so the schema carries the parameter burden. The description adds only that the id designates 'one finding' — no format, prefix, or lookup guidance. Baseline 3 is appropriate here.

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 how one finding stands to the others') and immediately defines the two directions of the relation: what it was built on and what has been built on it. That disambiguates it from siblings like get_finding (fetch a finding) and get_abstraction_graph, and the 'NEXT: link_findings' pointer names the write counterpart.

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 when-to-use rule with a rationale: 'Call this before you rely on a result' because a downstream finding inherits an upstream contradiction. It also routes the agent to link_findings for the inverse (write) operation. It stops short of naming a when-not condition or the alternative read tools (e.g., find_evidence_contradictions) an agent might confuse it with.

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 and openWorldHint=false, so safety is covered; the description adds genuinely non-obvious behavioral context about what the data represents and does not represent ('not settled transactions'). It stops short of describing freshness/recency guarantees or rate limits, so it is strong but not exhaustive.

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 trigger condition is front-loaded, the return inventory follows, then routing alternatives, then the interpretive caveat. Three dense sentences with no filler; the parenthetical capital abbreviations are the only mild redundancy.

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 an output schema present and annotations covering safety, the description only needs to cover intent and routing, both of which it does. Scope caveat, return shape and sibling alternatives are all present, so an agent can call this correctly on the first attempt.

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 documented in the schema and the baseline applies. The description only echoes the trailing-window concept ('over a trailing window') and never mentions the 'disease' keyword filter at all, so it adds little meaning beyond the structured fields.

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 a specific resource (the SI economy's four capitals: Material, Intelligence, Network, Diversity) and enumerates exactly what is returned (counts, directional pulse, sparkline, diversity/conscience index, top signals). It also names the sibling tools that cover adjacent ground, so an agent can separate it from get_trends_signal and get_batch_signals 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?

Opens with an explicit 'USE WHEN the question is about the SI economy' trigger and follows with concrete routing ('NEXT: call get_trends_signal ... or get_batch_signals'). It even states a scope boundary — published attention and announced capital, not settled transactions — which functions as a when-not signal.

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?

Consistent with readOnlyHint=true and openWorldHint=false. Beyond the annotations it discloses semantic traps: 'active' means recruiting or not yet recruiting, coverage gaps are not a ranking, and per-domain counts overlap so totals must come from the aggregate fields — exactly the kind of behavior that prevents a wrong call.

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 trigger and packed with useful detail, but the semicolon-chain and stacked parentheticals (alias note, active definition, totals pointer) make it a dense block rather than a scannable structure. Little is wasted, though the alias note could be shorter.

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-shape explanation isn't required, and the description still covers the interpretation gotchas (double counting, gaps vs ranking) plus the downstream workflow. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the one parameter is trivially described, so baseline is 3. The description still adds value beyond 'Agents to assign.' by explaining the effect: a deterministic split of N agents across domains and lanes, which tells the agent the output shape changes with swarm.

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 exact resource returned: 15 disease domains with MONDO/EFO ontology ids, indexed/active trial counts with an explicit definition of 'active', research links, and a per-domain parallel work plan. It also disambiguates from siblings by stating it replaces list_research_diseases and that overall totals live in totals.uniqueIndexedTrials/totals.uniqueActiveTrials.

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?

Opens with an explicit trigger ('USE WHEN starting disease research or a swarm'), gives a parameter-level usage rule (pass swarm=N for a deterministic split), an explicit anti-pattern (never sum per-domain counts), and a NEXT chain (get_disease_dossier, then lanes in parallel, then submit_finding). Alternatives and exclusions are stated 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=true and openWorldHint=false, so the safety profile is covered. The description earns credit on top by disclosing the payload structure and the notion of an 'effort profile' and cost in compute, which is what an agent needs to decide whether calling is worthwhile. It says nothing about volume, pagination, or size of the result set, which is the remaining gap for a list-style read.

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 call condition, then the resource, then the routing hint — the right order. The single long enumeration sentence is dense but every item listed is a genuine field of the return, so it earns its place. Slightly overstuffed for a three-sentence description.

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-optional-param, read-only tool with full schema coverage and an output schema, this covers everything an agent needs: trigger condition, scope of the return, how to narrow, and what to call next. Nothing essential 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 adds value by framing both arguments as optional narrowing selectors — 'narrow it to one question or one effort level' — which maps the abstract params to intent (id → single question, effort → effort tier). It does not explain the effort vocabulary, but the schema already supplies 'minutes, hours or sustained'.

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?

Specific verb+resource: it returns unanswered questions the platform cannot resolve alone, and it enumerates exactly what each record carries (effort profile, compute, why open, ordered endpoints, method, answer shape, falsification criteria). An agent knows precisely what comes back. It stops short of 5 because it never differentiates itself from adjacent discovery tools like open_rungs, next_work, or get_abstraction_graph beyond a sequencing pointer.

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 call condition is stated up front and in the imperative: 'CALL THIS WHEN YOU HAVE SPARE COMPUTE', which is a real gating signal rather than a generic hint. The 'NEXT:' clause adds follow-on sequencing. It lacks explicit when-not or an alternative tool to pick instead, which keeps it below 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 readOnlyHint=true and openWorldHint=true, so the safety and openness profile is covered. The description adds that results include disease-pathway flags and stable ids, which is useful, but says nothing about limits, pagination, or empty-result behavior beyond what the schema's limit parameter already implies.

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 clauses: what it does, when to use it, where to go next. Front-loaded with the core action and no filler; every sentence carries routing or scoping information.

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

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

With a full output schema and 100% parameter coverage, the description only needs to carry purpose and routing, which it does. Minor gap: it doesn't mention the limit cap or what happens when a gene has no pathways, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, with each of the four parameters documented inline, so the baseline is 3. The description only echoes the gene-symbol/UniProt duality already captured in the schema and adds no extra semantics for diseaseOnly or limit.

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 REACTOME PATHWAYS') plus the accepted identifier types (symbol or UniProt) and what the output carries (disease-pathway flags, stable ids). An agent can distinguish this from sibling lookups like get_gene or search_literature without opening the 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 usage context ('mechanism context before modelling') and names two concrete next-step alternatives (twin_experiment_guide for encoding a mechanism, search_literature for sources). It lacks an explicit 'do not use when' exclusion, but the routing guidance is actionable.

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 cover only readOnlyHint and openWorldHint; the description goes well beyond by explaining what the degraded flag and sync timestamp mean for result validity, and imposes a behavioral duty to label results partial. That is genuine operational context an agent could not infer from structured fields.

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 precondition in caps, then the payload, then the routing. Every sentence carries distinct actionable content; nothing is restated from the schema or annotations.

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 zero parameters, an output schema present, and read-only annotations, the remaining burden is interpretation guidance, which the description supplies (degraded/stale implies partial evidence). Nothing needed to call or act on the 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It does note that registry filtering happens downstream via search_world_trials, which usefully rules out a non-existent parameter.

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?

It states a specific verb and resource ('Returns every upstream registry') and enumerates exactly what comes back (base URL, API type, licence, record count, last sync time, degraded flag, schema-contract verdict). It is clearly distinguishable from get_trial_stats and search_world_trials, which are named as follow-ups.

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 opening imperative gives a concrete trigger ('USE BEFORE PRESENTING TRIAL EVIDENCE AS CURRENT OR WORLDWIDE') and the NEXT clause names two alternatives with the exact condition for choosing each, including the deliberate single-registry case.

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 and openWorldHint=false, so the safety profile needs no restating, and the description correctly does not restate it. What it adds beyond annotations is structural disclosure of the response payload (traversal, honesty rule, open question) and that filtering is optional, which is useful but does not address pagination, volume, or caching behavior. Given annotation coverage, this is a solid but not exceptional contribution.

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 trigger condition, then scope, then the follow-up chain — a good decision-first ordering with no filler sentences. It is long and sentence-dense, with the payload enumeration running as a comma list, which costs a little readability for a reader skimming.

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, yet the description still previews the payload sufficiently to set expectations. It covers the trigger, the content, the optional narrowing, and the next-tool chain, leaving nothing an agent needs in order to call this 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 semantic framing the schema lacks: the arguments are optional and 'narrow it to one objective or one difficulty level,' clarifying that filtering is a scoping convenience rather than a requirement. It does not name the parameters, which the schema handles well enough, but the optionality emphasis is meaningful extra guidance.

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 ('Returns the standing research objectives of the Cure protocol') and enumerates exactly what each objective contains (mandate, rationale, canonical traversal, deliverable, honesty rule, open question). The opening trigger phrase 'CALL THIS WHEN YOU HAVE CAPABILITY BUT NO ASSIGNMENT' implicitly separates it from work-assignment siblings like next_work, so an agent can route without opening the 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 invocation condition (capability but no assignment) and a concrete follow-up chain: 'NEXT: get_registry_sources to establish scope, then the trial tools named in the traversal.' This is when-to-use plus sequencing, not just a description of contents.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: 'Unconfirmed leads never reveal how many others agree,' which tells the agent the response is deliberately truncated for unconfirmed records rather than missing data.

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 action and resource, then the payload contents. Every clause earns its place; nothing is repeated from the title or annotations.

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 an output schema present, return-shape explanation is unnecessary, and readOnlyHint covers safety. The description supplies the payload summary and the visibility caveat; only the routing relationship to sibling tools is unstated.

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% for the single 'id' parameter, so the schema already carries the semantics. The description adds no format, source, or lookup guidance for the id beyond what's structured, 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?

States a specific verb (read) and resource (a receipt for one Results Gap report) and enumerates the contents: trial, paper, PubMed verification, confirmed vs. lead. It's clear what the tool returns, though it never names the sibling next_results_gap_trial or submit_results_gap to sharpen the boundary.

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 by requiring an id: fetch a single receipt you already have an identifier for. There's no explicit statement of when to use this versus next_results_gap_trial (to find one) or submit_results_gap (to create one).

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: counts are "live" (not cached), a rolling 24-hour window for traffic, and an explicit "list of things this scoreboard deliberately cannot measure" that warns the agent about scope limits. It stops short of stating freshness/staleness semantics or failure modes, so not 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?

The critical directive and next-step routing are front-loaded and the middle is a single dense enumeration, but that enumeration is long and overlaps with what the output schema already exposes. It earns most of its space, though a shorter phrasing could carry the same signal.

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 an output schema present, the description needn't enumerate returns, yet it gives the agent enough to know scope, when to call it, known blind spots, and where to go next. For a zero-parameter, read-only dashboard tool this is 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?

Zero input parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no words on arguments and instead describes the return payload.

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 ("Returns live counts of trial registrations, deduplicated canonical trials, active trials, cross-registry trials, reframed articles and cure research items") plus secondary counts and a 24h traffic summary. This is clearly distinguishable from siblings like get_trial_stats or get_api_status, which expose narrower slices.

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 opening imperative "CALL THIS BEFORE QUOTING THE SIZE OF THIS INDEX" gives an explicit trigger condition, and the trailing "NEXT: get_api_status for reliability, get_open_questions for work" routes the agent to the correct sibling for adjacent needs. Nothing about when to reach for this tool 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 readOnlyHint=true and openWorldHint=false, so the safety and scope profile is covered structurally. The description adds genuinely new context — that coverage is exhaustive ('every T1D trial in the index') and that responses include ledger counts — but says nothing about the samples cap (max 25) or how results are ordered or paginated.

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 core capability is front-loaded in one dense sentence, followed by a short routing hint; nothing is padded. The all-caps lead and parenthetical enumeration make it slightly hard to scan but the sentence budget is tight.

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 and all three parameters are documented, so the description carries little return-value burden. The remaining gap is disambiguation: with get_trial_landscape, get_trial_coverage and get_trial_stats as siblings, an agent needs an explicit statement of what this tool uniquely answers, and it is absent.

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 would be 3. The description goes beyond the schema by decoding the track letters (A tolerance, B beta-cell restoration, C graft protection, D combination, E immunogenetics), which the schema does not explain at all — a real semantic gain for the most consequential parameter.

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 (map T1D cure research trials in the index) and enumerates the dimensions it organizes by — track, disease stage, outcome rung, ledger counts. The T1D qualifier and the A–E track taxonomy separate it from the generic sibling get_trial_landscape, though the description never explicitly acknowledges that near-identical sibling.

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?

'NEXT: search_cure_evidence or submit_evidence' gives a follow-on path but not a when-to-use-this-vs-alternative rule. The strongest alternative, get_trial_landscape, is never mentioned, so an agent must infer the difference from the name.

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 and openWorld, but the description adds a genuinely non-obvious interpretive caveat: "Scores are source data, not a ranking," which prevents misuse of the numeric output. It doesn't mention behavior for unresolved identifiers or how many ontology terms are returned, so not 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?

Three dense sentences, front-loaded with the verb and resource, then the evidence taxonomy, then the interpretive caveat, then routing. No filler or restatement of the tool name.

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 described, and the description supplies the interpretive frame (evidence types, scores are not rankings) plus next steps. It omits edge-case behavior — e.g., what happens when the gene–disease pair has no ontology associations — which matters given openWorldHint=true.

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 earns a bump by tying "per ontology term" to the ontologyId parameter — clarifying that it scopes/groups the evidence breakdown rather than just filtering. It says nothing additional about the gene or disease parameters beyond the schema's own HGNC/domain-id 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 ("EXPLAIN A GENE-DISEASE LINK") and immediately specifies the unit of output ("per ontology term") plus the dimensions of the breakdown (evidence type, data source). This cleanly separates it from siblings like get_disease_targets or get_target_profile without needing the 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 "NEXT:" clause explicitly routes the agent onward — get_target_profile for druggability and safety, search_literature for papers — which is real alternative-selection guidance. It lacks an explicit "use this instead of X when..." framing or any preconditions on gene/disease identifiers, 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 readOnlyHint and openWorldHint, so the safety profile is covered. The description adds substantive content context — what data types are returned (pLDDT scores, PDB/CIF links) — which goes beyond the annotations. Minor gap on freshness/rate behavior.

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

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

Two dense sentences with the resource and content list front-loaded, followed by a compact routing clause. No wasted words.

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 an output schema present, return values needn't be fully explained, yet the description still signals the profile's content areas and the natural next steps. Sufficient for an agent to call correctly with the right follow-ups.

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 documented as 'HGNC symbol or ENSG id.' The description adds nothing about the symbol parameter, so baseline 3 is appropriate since the schema carries the load.

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 ('PROFILE A DRUG TARGET') and enumerates the profile's contents — tractability, genetic constraint, safety liabilities, essentiality, chemical probes, location, interactions, AlphaFold structure. This is clearly distinguishable from siblings like get_target_evidence or get_gene.

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 'NEXT' clause explicitly routes the agent to get_expression for expression and search_compounds/find_repurposing_leads for molecules, giving clear follow-on guidance. It stops short of stating when NOT to use this tool or contrasting with get_target_evidence directly.

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 and openWorldHint=false, so safety is covered. The description adds meaningful context about contents (7-day momentum, 30-day daily series, curated crypto TGE list contrasted with live cure-research capital) and a payload trade-off. It does not discuss freshness or computation cost, but adds solid behavioral 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?

The critical 'USE WHEN' clause is front-loaded and the description is short overall. The middle sentence is a run-on that stitches crypto TGE scoring and cure-research capital into one breath, slightly hurting scannability.

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 an output schema and read-only annotations already present, the description needs only to explain what the signal covers and how to route between it and get_mind_signal, which it does. It omits mention of the include/disease narrowing behavior, but the schema carries that.

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 all three parameters are already documented. The description only reinforces the series=false slimming behavior and says nothing about the disease filter or the include section list beyond what the schema provides. 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 (attention dynamics: momentum and 30-day series across categories and research domains) and distinguishes it from the level-oriented sibling get_mind_signal. The purpose is clear, though the crypto-token-generation-event clause is dense and slightly obscures the core 'trends' framing.

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 opens with an explicit 'USE WHEN you need attention dynamics rather than levels,' names the alternative ('NEXT: get_mind_signal for the capital levels'), and gives a payload-slimming instruction (series=false). The selection condition and follow-up path are both 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?

The annotations already establish read-only and closed-world behavior, and the description adds substantial behavioral context beyond that: it computes distinct-trial counts across registries, identifies duplicate registrations, reports registry exclusivity, and calculates the inflation from naively summing registry totals. That directly explains what the tool does differently from a simple count tool and why it prevents overcounting.

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 front-loaded with the critical instruction and then explains the computed outputs in one dense sentence. The remaining sentences add usage context and next-step routing without wasting 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?

Given the 19-parameter schema with full description coverage, an output schema, and read-only annotations, the description provides everything an agent needs to select and invoke this tool correctly. It explains the analytical purpose, the filter compatibility, and the correct neighboring tools.

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

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

Schema description coverage is 100%, so the schema already carries the parameter semantics and the baseline is 3. The description adds a useful cross-reference that it accepts the same filter vocabulary as `search_world_trials`, but it does not add per-parameter meaning beyond the schema.

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 precise analytical purpose: it answers how many DISTINCT trials exist, how many are duplicate registrations, which trials are registry-exclusive, and what the `inflation` overcount would be. It clearly distinguishes this coverage/deduplication role from sibling tools such as `search_world_trials` for records and `get_trial_landscape` for structure.

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 an explicit trigger: 'USE BEFORE STATING ANY WORLDWIDE COUNT.' It also names the alternatives and when to use them: `search_world_trials` for the records themselves and `get_trial_landscape` for their structure.

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 readOnly/openWorld; the description adds substantive behavior the annotations cannot: a warning to read `fieldCompleteness` before quoting any distribution, and the disclosure that `evidenceGap` deliberately refuses to publish a combined figure when registry flags are incomparable. That is exactly the kind of output-interpretation and limitation context annotations can't carry.

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 selection rule and alternatives at the end; nearly every clause carries distinct information. It is dense and reads as a run-on block of caveats, 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?

For a 19-parameter analysis tool with an output schema (so return shape needn't be described), the description supplies the missing interpretive layer: completeness caveats, the deliberate non-reporting behavior of evidenceGap, and the workflow handoffs. Nothing an agent needs to call and interpret it correctly is absent.

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?

With 100% schema description coverage across 19 parameters, the schema already documents each filter (including enum-like values for status, registry, studyType), so the baseline is 3. The description adds a little interpretive value, notably that phase is missing for much of the corpus and that restricting to one registry yields single-registry evidence, but it doesn't explain parameter interactions or defaults.

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

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

The description opens with a specific verb-plus-resource framing ('the SHAPE of a research field rather than a list of its members') and enumerates the exact outputs: phase/status/study-type mix, sponsor concentration, enrollment scale, reporting gap, momentum, snapshot diff. This cleanly separates it from search_world_trials, which returns member trials.

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?

'USE WHEN you need the SHAPE ... rather than a list of its members' gives an explicit selection condition, and the NEXT clause names the follow-up tools (search_world_trials to drill into a bucket, get_trial_coverage for duplicate registrations) with their distinct purposes. Both when-to-use and the alternatives are stated outright.

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?

Although readOnlyHint/openWorldHint already mark it as a safe open read, the description adds substantial context the annotations cannot: the three-layer structure, the kind=results/background/derived/protocol taxonomy, the open-access and citation fields, and the critical inIndex true/false distinction with an explicit instruction never to report an inIndex=false identifier as a held trial. That is exactly the kind of provenance/destruction-adjacent warning the burden falls on the description to carry.

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?

Well front-loaded with the USE WHEN trigger, then returns, then the sidecar caveat, then NEXT routing. It is on the long side, and the enumeration of registries (ANZCTR, ChiCTR, JPRN, DRKS, CTRI, CTIS and more) is the one passage that could be trimmed without losing decision-relevant 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 three-parameter read tool with an output schema, the description covers everything an agent needs: precondition, argument source, shape and semantics of each returned layer, the double-counting trap, and where to go next. No ambiguity remains about how to call it or how to interpret what comes back.

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 earns an extra point by naming the three layers in a way that maps onto the include sections (declared/literature/crossref) and clarifying that crossRegistryMentions comes from literature abstracts. It adds no syntax guidance for limit or include beyond what the schema already documents, so it stops short of 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 verb+resource (fetch published research and cross-registry mentions around a trial) and enumerates the three labelled output layers, each with the meaning of its fields. It explicitly separates itself from search_literature, get_world_trial and find_trial_registrations, so an agent can pick 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?

"USE WHEN you have a trial (canonicalId from search_world_trials)" gives a precise precondition and names the upstream producer of the argument. It also closes with explicit routing (get_world_trial for the canonical record, find_trial_registrations for double-counting) and warns that nothing returned here is in the index or any count.

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 readOnly and closed-world, and the description adds non-obvious semantics: registry counts are never summed (each reported separately alongside a distinct total), and diseaseDomains figures reconcile exactly with get_mission_map. This is real interpretive context not derivable from the annotations, though a good share of the text restates return fields that the output schema already carries.

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 trigger, then the payload, then the counting caveat, then routing — good ordering with zero filler sentences. It is slightly long because the field enumeration repeats what the output schema already lists.

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 an output schema, no parameters, and read-only annotations, nothing an agent needs to call this correctly is missing: it knows the trigger, the shape of the answer, the counting convention, and where to go next.

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?

Zero parameters, so baseline 4 applies. The description additionally documents the `topic` ids surfaced by this tool as valid inputs to other trial tools, which is useful cross-tool parameter context even though this tool itself takes nothing.

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?

Specific verb+resource: it returns index-wide counts (source records, deduplicated canonical trials, active count, per-registry attribution, topic ids). It distinguishes itself from neighbors by explaining the reconciliation relationship with get_mission_map and by routing to search_world_trials for queries.

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?

Opens with an explicit trigger ("USE WHEN orienting on the trial corpus or answering a whole-index count") and closes with a NEXT clause naming the exact follow-on tools (search_world_trials, get_registry_sources) and what each is for.

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 and openWorldHint=true, so safety/side-effect profile is covered. The description usefully adds that this is reference data and never personal genotypes — an important scoping disclosure not encoded in annotations — but says nothing about lookup failures (unknown rsID), latency, or caching behavior. An output schema exists, so return shape need not be covered; a 3 reflects the modest additional 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?

Three compact clauses: what it returns, the scope constraint, and the next step. Nothing is repeated or wasted, and the payload (fields returned) is front-loaded.

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

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

With one required param documented in schema, an output schema present, and readOnly/openWorld annotations, the description covers the remaining gaps (scope and follow-up). Minor omission: no mention of behavior for an unmatched or invalid rsID.

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?

Only one parameter and schema description coverage is 100%, with the schema providing the dbSNP format and an example (rs2476601). The description's 'by rsID' restates rather than extends that. 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?

States a specific verb and resource ('ANNOTATE A PUBLIC VARIANT by rsID') and enumerates exactly what comes back: alleles, genes, ClinVar significance/conditions, gnomAD frequency, predicted consequence. The 'public variant / reference data only' framing also separates it from the patient-oriented siblings in the tool list.

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?

Adds an explicit routing line ('NEXT: get_gene or search_literature'), which tells the agent where to go for follow-up. It does not state exclusions or prerequisites explicitly, but 'Reference data only, never personal genotypes' implicitly bounds when this tool applies versus patient tools.

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

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

Beyond readOnlyHint/openWorldHint, it discloses non-obvious behavior: includeRaw returns the untouched stored payload only after contact-field redaction, and it characterizes that as the strongest available evidence. That redaction caveat is exactly the kind of detail an agent cannot infer from annotations or 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?

Front-loaded with the triggering condition and organized into use / includeRaw / NEXT blocks, with no filler sentences. Slightly dense with stacked parentheticals and caps emphasis, but each clause carries distinct 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 needn't be spelled out, yet the description still conveys the shape of the result (normalized fields + source records). Precondition, option semantics, and follow-on tools are all covered — nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining what includeRaw is actually for (field-by-field claim verification) and its redaction caveat, plus noting canonicalId provenance. It stops short of the top mark because canonicalId's own format/failure semantics are left entirely to the schema example.

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 (fetch the COMPLETE trial record for a canonicalId) and enumerates exactly what completeness means: normalized fields plus registry, source id, source URL, retrieval timestamp and payload checksum. It also names the two sibling tools that produce a canonicalId (search_world_trials, find_trial_registrations), so an agent can distinguish it from them without opening 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?

Opens with an explicit precondition ('USE WHEN you already have a canonicalId') and attributes where that id comes from. It also gives a follow-on routing section ('NEXT: find_trial_registrations ... get_registry_sources'), covering both entry and continuation paths.

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 and openWorldHint=false. Beyond that, the description discloses the orientation payload, the presence of a resume cursor, the published rate budget, and the recommended next calls, adding useful behavioral context without contradicting annotations.

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 front-loaded with 'START HERE' and 'Call this before anything else'. Every sentence earns its place by naming the payload, the mandatory ordering, and the next-step alternatives.

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 zero parameters, read-only annotations, and an output schema, the description provides everything needed for an agent to decide to call this first. It also routes the agent to claim_work or whats_new afterward, completing the onboarding context.

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 has zero parameters, so there is no parameter semantics to explain. The baseline for 0 params is 4; the description cannot add parameter meaning because none exist.

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: a single orientation call for a new agent. It enumerates what the call provides (protocol, live board state, best work item, resume cursor, rate budget), distinguishing it clearly from siblings like claim_work and whats_new.

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 sequencing: 'START HERE', 'Call this before anything else', then 'NEXT: claim_work' or 'whats_new later to catch up'. This tells the agent when to use this tool and which alternatives follow in the workflow.

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=false, idempotentHint=true, destructiveHint=false, and the "WRITES:" prefix aligns with them. The description adds real context beyond the annotations: that contradicting is a first-class act and not a conflict, and where to go afterwards. It stops short of explaining duplicate-link behavior or failure modes.

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 action and the relation list, then a motivating sentence and a next-step pointer. No filler, and the most decision-relevant content comes first.

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 five-parameter write tool with an output schema, the description covers purpose, relation semantics, and follow-up. It leaves minor gaps such as behavior on duplicate links, but nothing an agent needs in order 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 each of the five parameters is documented in the schema, so the baseline is 3. The description restates the relation values but adds no syntax or format detail beyond what the schema already provides.

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+resource ("DECLARE how your finding relates to an existing one") and enumerates the exact relation vocabulary. An agent can distinguish this from submit_finding and get_lineage 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?

Provides clear context for use (turning separate results into a followable body of work) and an explicit next step ("NEXT: get_lineage on either id"). It doesn't name an alternative for cases where a link shouldn't be created, but the guidance is otherwise concrete.

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