OpenCancer

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

Adds substantial context beyond the readOnly/idempotent annotations: language mirroring, the refusal/routing behavior for emergencies and prognosis, the PII restriction, and the educational-not-medical-advice stance. Annotations cover safety profile; this description covers the semantic and ethical behavior an agent needs.

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

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

Front-loaded with purpose and grounding, then coverage, then output shape and safety carve-outs. Slightly dense with the long topical enumeration, but every clause adds routing or behavioral value.

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

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

An output schema exists, so return-value enumeration beyond the brief mention is unnecessary. The description nonetheless anticipates the key behavioral edge cases (refusals, PII, educational framing) an agent needs to invoke 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% with each parameter's description covering purpose, format, and the no-identifier constraint. The description only restates the 'no personal identifiers' rule and language behavior, which the schema already documents, so it adds little beyond baseline.

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

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

States a specific verb (answers), a specific resource (cancer patient/caregiver questions), and the grounding sources (NCCN Guidelines, medical literature). It enumerates concrete topical coverage that distinguishes it from the trial/feedback/case siblings.

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

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

Explicitly names when NOT to use the answer path: emergencies, prognosis/life-expectancy, and pediatric questions route to a safety message and the care team. The topical list also implies when to reach for this tool versus siblings like find_clinical_trials.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real value beyond them: a cap of 8 results, the exact return contents, and the important scope caveat that 'listing a trial is not an eligibility decision'. Rate limits or refresh behavior are not disclosed, keeping it below 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?

It is front-loaded with the core action and scope, then the filters, then return contents, then the eligibility disclaimer — a logical order with no filler. The enumeration of return fields is slightly long, but each item is informative and the whole thing remains two sentences.

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

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

For a search tool with an output schema, the description still covers the essentials: source registry, result cap, filter dimensions, and the eligibility limitation that an agent must not over-interpret. Nothing needed to call it correctly or set user expectations 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%, so all four parameters (condition, location, keyword, phase) are already documented in the schema with examples and length limits. The description restates their roles in prose ('near a city, state or country', 'a biomarker, drug or treatment keyword and by phase') but adds no syntax or format detail beyond that, matching the baseline of 3 when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('Lists clinical trials recruiting now for a cancer type, from ClinicalTrials.gov') plus the scope of the result set. It is clearly distinguishable from siblings like get_trial_details and ask_opencancer, which operate on a single trial or a conversational expert rather than a filtered search.

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

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

It states when to use it — searching by cancer type, optionally narrowed by location, biomarker/drug keyword, or phase — and adds an escalation cue by advertising a link to an OpenCancer expert who can build a shortlist. It stops short of explicitly naming the sibling tool to call for those follow-ups, so it is clear context rather than full when/when-not 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 declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that: it discloses that criteria are returned in 'original wording' and, critically, that 'Eligibility is confirmed only by the study team' — a caveat that prevents the agent from presenting registry criteria as an eligibility decision.

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 long but front-loaded sentence that puts the verb, resource and identifier first, then enumerates returned fields. Nothing is wasted, though the field enumeration is dense and the sentence could be broken for readability.

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

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

With an output schema present, the enumerated return fields are partly redundant, but the description still supplies the eligibility caveat and the 'original wording' nuance that structured fields cannot convey. Nothing needed to call the tool 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%: nct_id is documented with an example and a regex pattern. The description's 'by its NCT number' merely restates the parameter's meaning without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource+scope: 'Returns one clinical trial from ClinicalTrials.gov by its NCT number.' The singular 'one' plus the registry identifier cleanly separates it from the sibling find_clinical_trials search tool without even needing to name it.

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 need for an NCT number implies this is the lookup-by-ID path rather than a search path, but the description never explicitly says when to use it instead of find_clinical_trials, nor does it name that alternative. Usage is inferable but not 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 readOnly/idempotent/non-destructive, and the description adds material context beyond them: the link opens only an intake page, no case is created, no records are transmitted, and the patient personally confirms consent. This correctly warns the agent that calling the tool has no data-side effects, which is exactly the behavioral detail needed here.

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 what the tool returns, then the privacy/consent caveats. Dense and nearly waste-free, though the final sentence partially restates the earlier 'no records are sent' point from an input rather than output angle.

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 format needn't be described. The description covers the read-only nature, consent flow, and intake-only behavior, which is enough for a zero-required-parameter link generator. It could still note link delivery or expiry, but nothing critical is missing.

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

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

Schema coverage is 67%, so most parameters are self-documented. The description adds a useful negative constraint ('accepts no names, contact details or records') that shapes how the question field should be filled, but it says nothing about cancer_type or the preferred_destinations enum values, leaving those entirely 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?

The description states a specific verb and resource: it returns a link that lets a patient start an expert review by named organizations, enumerating what the review covers (records, options, trial shortlist, next step). That is unambiguous and clearly distinct from siblings like find_clinical_trials or send_feedback, though it never names an alternative tool to route to.

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

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

Usage is implied rather than stated: the patient wants an expert review, so the agent calls this. There is no explicit when-to-use/when-not guidance and no comparison against ask_opencancer or find_clinical_trials, which an agent could plausibly confuse with this 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 establish that this is a write (readOnlyHint=false) but not destructive or open-world. The description adds genuinely new behavioral context: the feedback goes to the OpenCancer team, no reply is sent back through it, and it is explicitly not an urgent-care channel. That is exactly the kind of downstream consequence annotations cannot express.

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 tight sentences with the primary action front-loaded before the trigger conditions and the behavioral caveats. Dense but not padded, though the third sentence stacks several caveats together and could be split for easier scanning.

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 need not describe return values, and annotations cover the safety profile. What remains — when to use it, which kind to pick, what happens to the feedback, and the no-reply expectation — is fully covered for a 4-parameter reporting 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 a baseline of 3 applies, but the description adds real semantics by explaining the interplay between fields: answer_id identifies the answer, message carries the user's own words, and the 'missing_answer' kind pairs with answer_id or tool and no message. It stops short of explaining the remaining enum values (bug, idea, praise) beyond their self-evident labels.

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 specific verbs and resources: flagging an OpenCancer answer for expert review, and sending feedback to the team. It is clearly distinguishable from every sibling (ask_opencancer, find_clinical_trials, get_trial_details, open_case), all of which are retrieval tools rather than reporting channels.

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?

Enumerates concrete trigger conditions: the answer was wrong, unsafe, or incomplete; the user wants to tell OpenCancer something; or a tool returned no usable answer. It even prescribes the right kind value ('missing_answer') and the parameter combination for that case, 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.