get_evidence

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 only that the tool surfaces citation/DOI/finding content, but says nothing about batch lookup behavior, what happens with invalid or unknown ids, or cardinality of the result set. Modest added value over 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?

A single tight fragment with no filler, and the returned fields are front-loaded. It is under-specified rather than padded, and the missing verb makes the sentence slightly harder to parse than a well-formed clause would be.

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

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

There is no output schema, so the description carries the burden of explaining what comes back – it does name the returned fields (citation, DOI, finding). However, it omits where valid ids originate and any error or empty-result behavior, leaving the lookup workflow only partially specified for a one-parameter retrieval 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 0% for the single 'ids' array, so the description is the only source of meaning and it gives just the semantic anchor 'evidence ids attached to scores and insights'. It does not clarify the id format, whether ids are opaque strings, or how many can be passed. This partially compensates for the schema gap but leaves format 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?

The description names the precise payload returned – 'Citation, DOI and finding' – and the key that retrieves it, 'evidence ids attached to scores and insights'. That is enough for an agent to know this is a lookup for evidence records behind scores/insights. It lacks an explicit verb and does not reference any sibling, but no sibling returns evidence metadata, so differentiation is implicit.

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?

There is no when-to-use statement, no mention of where the required 'evidence ids' come from, and no alternatives or exclusions. The phrase 'attached to scores and insights' hints at provenance but never tells the agent when to call this versus get_overview or query_sql.

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