jp_lit_refine_results

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

Beyond the annotations, the description discloses that it never mutates cache or session, never re-queries upstream even when enrichment is enabled, and only overlays saved enrichment caches conditionally. This gives an agent a precise behavioral model not inferable from readOnlyHint/idempotentHint alone.

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 behavior is front-loaded, and the description packs the important constraints into a compact form. It is slightly dense and has minor redundancy between 'read-only' and 'cacheやsessionは変更しない', but every distinct behavior is covered without 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?

For a tool with no input schema and an output schema, the description adequately covers targeting, no-upstream behavior, enrichment overlay conditions, and non-mutation guarantees. It does not spell out the exact refinement operations or cluster-request semantics, but those are likely expressed in the output schema or request parameters.

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 input schema is empty, so the description is the only source for parameter meaning. It names cache_key, cache_keys, session_id, include_enrichment, and enrichment_cache_keys, and explains their roles. However, the sort/filter/set-operation parameters are not explicitly enumerated, leaving some 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 states a concrete action: refine saved jp_lit_search results locally via sort/filter/set operations without upstream re-search. It distinguishes itself from siblings like jp_lit_search and jp_lit_enrich_record by emphasizing it operates on cached results and never queries Crossref/OpenAlex.

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 clearly indicates this tool is for refining already-saved jp_lit_search results and names cache_key/cache_keys/session_id as the targeting mechanism. It also routes cache_key discovery to jp_lit_search_cache_index or jp_lit_list_cache, but does not explicitly state when to prefer this over running a new search.

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