Finds the closest Semantic Scholar title match for a given paper query and returns its unscaled numeric match score.
Find the closest title match; preserve S2's unscaled numeric matchScore.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Changes observed during successful MCP inspections.
v1.2.13Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "title": "Result",
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "title": "match_paperOutput",
- "type": "object"
-}New value: +nullv1.2.6Input schema / $defs / PaperMatchInput / properties / api_key / deprecatedAdded value: +trueInput schema / $defs / PaperMatchInput / properties / api_key / descriptionPrevious value: -"API key (overrides SEMANTIC_SCHOLAR_API_KEY env var)"New value: +"API key (overrides SEMANTIC_SCHOLAR_API_KEY env var). Deprecated: prefer the environment variable. Removal planned for v2.0.0."v1.0.3Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, open-world behavior. The description adds useful behavioral context by noting that S2's unscaled numeric matchScore is preserved, but it does not mention rate limits, auth behavior, or what happens when no match is found.
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 clauses, front-loaded and free of filler. Every phrase contributes either the core purpose or a notable behavioral detail.
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 one-parameter lookup tool with safety annotations, the description is minimally sufficient. It does not explain output beyond matchScore, nor does it cover no-match behavior or output-format differences, which matters because there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description implies the required query parameter is a paper title, which adds some meaning beyond the formal schema. However, schema description coverage is reported as 0%, and the description does not clarify response_format or the deprecated api_key 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?
The description states a specific operation: finding the closest title match. It clearly identifies the resource as a paper title, though it does not explicitly distinguish itself from sibling search/get tools.
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 by 'closest title match', suggesting it should be used for title-based lookup rather than broad search. However, it does not explicitly say when to prefer this over semantic_scholar_search_papers or semantic_scholar_get_paper.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.