mechoulam.de Cannabis Evidence Register

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral value by specifying that it returns exactly one full record, that the record type is either an indication summary or a study with per-indication verdicts, and that a source URL for citation is included. No contradiction with the 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?

Two sentences with no filler: the core action, the input provenance, the possible record types, and the citation URL are all covered. The most important scoping information 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 a single well-documented parameter, a read-only annotation, and an output schema present, the description is complete for an agent to select and call the tool correctly. It also preempts confusion about which record type may be returned and provides the citation detail.

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% for the single id parameter, and the schema description already says 'Id from a search result.' The description reinforces this same meaning but adds little new semantic detail beyond what the schema provides, so the baseline of 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 names a specific verb ('Fetch'), a specific resource ('one full record by the id returned from search'), and the two possible record types (GRADE-rated evidence summary or study with verdicts). This clearly differentiates it from the search and list siblings, and even from get_indication/get_study by emphasizing the unified id-based fetch.

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

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

It tells the agent this tool is used with an id returned from search, implying it should be called after search rather than as a standalone query. It does not explicitly name alternatives or exclusion conditions, but the id-from-search guidance is clear contextual usage direction.

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 provide readOnlyHint=true, so no safety contradiction exists. The description adds behavioral value by stating that only reviewed studies are included and that the evidence is GRADE-rated, which tells the agent what kind of content to expect without relying on the schema.

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

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

The description is two tight sentences, front-loading the core action and then giving the one essential usage instruction. There is no filler, repetition of schema details, or unnecessary explanation.

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

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

For a simple lookup tool with two well-documented parameters, safe read-only annotations, and a clear source of valid slugs, the description covers everything an agent needs to invoke it correctly. The absence of an output schema is mitigated by the phrase 'GRADE-rated evidence summary', which adequately conveys what will be returned.

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 schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantic guidance by telling the agent that the slug should come from list_indications, which is exactly the operational knowledge needed to call the tool correctly.

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 begins with a specific verb and resource: 'Get the GRADE-rated evidence summary for one indication'. It adds important qualifiers ('reviewed studies only') that distinguish this from searching or fetching raw studies. It even points to the sibling list_indications as the source of valid slugs, making the tool's role in the family clear.

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 instruction 'Use a slug from list_indications' gives a clear precondition and points to the correct data source. It does not explicitly enumerate alternatives or say when not to use this tool, but for a single-purpose lookup the context is sufficient.

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 readOnlyHint annotation already signals a safe read operation. The description adds value by disclosing that only reviewed verdicts are included and that the response is organized per indication, which is behavioral context beyond the annotation.

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 short, front-loaded sentence with no filler. Every word earns its place, and the key identifier and include-filter are both mentioned efficiently.

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

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

For a simple two-parameter read-only tool, the description covers the input, the lookup key, and the return content sufficiently. The absence of an output schema is partially compensated by 'per-indication verdicts (reviewed-only)', though a bit more detail on the return shape 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 the schema already documents both doi and lang. The description reinforces that the study is looked up by DOI but adds no new parameter-level detail 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 names a specific verb and resource ('Get one study by DOI') and adds a distinctive detail ('with its per-indication verdicts (reviewed-only)') that separates it from siblings like get_indication or list_indications. An agent can immediately infer what this tool returns and what identifier it needs.

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

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

The phrase 'Get one study by DOI' gives a clear context for when to use this tool: when the agent already has a DOI and needs that specific study's verdicts. It does not explicitly name alternatives or exclusions, but the context is clear enough to avoid obvious misuse.

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, so the safety profile is covered. The description adds the scope ('all indications') and expected fields, but does not disclose pagination, ordering, completeness guarantees, or response shape beyond field 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?

A single well-structured sentence places the core action first and lists fields compactly. No filler or duplication.

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

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

For a read-only list with one optional parameter, the description names the output fields and scope, which is nearly sufficient. It lacks only explicit ordering/pagination details, which are unlikely to be critical for an enumeration endpoint.

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%; lang is fully described in the schema. The description does not add language nuances or default behavior beyond what the schema states.

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 ('List'), a resource ('indications on mechoulam.de'), and enumerates the returned fields. This distinguishes it from sibling get_indication, which appears to target a single indication.

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

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

The phrase 'List all indications' clearly implies an enumeration use case, but the description never names alternatives like get_indication or states when to prefer this tool. No explicit exclusions or conditions are provided.

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 the description does not contradict them. It adds useful behavioral context beyond the schema: the result includes citable URLs and that the answer language follows the query language, which is non-obvious and relevant for invocation.

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 with no filler. The core purpose and scope are front-loaded, followed by return contents and a language behavior note. Every sentence earns its place.

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 search tool with an output schema and clear annotations, the description covers what the tool searches, what it returns, and a language-specific behavior. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents the single query parameter. The description adds meaning by specifying what kinds of free text are valid (indication, condition, drug, study title, author), which is valuable beyond the bare 'Search query' schema text.

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

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

The description names a specific verb ('Search'), a specific resource (the mechoulam.de cannabis-medicine evidence register), and enumerates the searchable fields (indication, condition, drug, study title, author). It also states what it returns, clearly distinguishing it from the more targeted sibling tools get_indication, get_study, fetch, and list_indications.

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 clearly implies this is the free-text search entry point across the register, which sets expectations for when to use it versus direct lookup or listing tools. It does not explicitly name alternatives or exclusion conditions, but the 'by free text' qualifier gives enough context for an agent to route correctly.

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