uniprot-mcp-server

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

Beyond the readOnly/idempotent annotations, the description adds key behavioral details: partial failures populate succeeded[] and failed[], oversized records trigger an 'outline' response with byte sizes, and isoform suffixes must be stripped before calling. This is substantial non-obvious behavior an agent needs to know.

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 longer than the typical two-sentence ideal, but every sentence carries substantive information: batch behavior, entry contents, trimming, outline handling, and source requirement. It is front-loaded with the core purpose and uses structured clauses without unnecessary fluff.

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?

Given the presence of an output schema and annotations, the description sufficiently covers the remaining workflow: batch size, partial failure results, oversized record handling, section re-calls, accession sources, and preprocessing requirements. It is complete enough for reliable tool invocation and adaptation.

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 all parameters at 100% coverage. The description adds valuable usage semantics beyond schema: 'fields' is for trimming the initial projection, 'sections' is only used for re-calls after an outline and should not be passed initially, and accessions require canonical form with suffixes stripped.

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?

Description opens with a specific action: 'Fetch full curated UniProtKB entries by accession in one batch (up to 20)', clearly identifying the tool's resource and scope. It also distinguishes itself from search behavior with 'This tool does not search', preventing confusion with sibling 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?

The description provides explicit guidance on when not to use this tool: 'This tool does not search: accessions come from uniprot_search_proteins.results[].accession or uniprot_map_ids.' It also explains the workflow for trimming fields initially and using sections only after an 'outline' response, which guides invocation steps.

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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses concrete behavior: the returned metadata fields, large protein set size (~147,506 for human), capped pages with a forward cursor, and optional query filtering. This gives the agent strong expectations about cost and paging behavior.

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 dense but efficient, with no filler. Each sentence carries distinct value: what the tool fetches, what metadata comes back, how proteins are paginated and filtered, and what to call first for organism names.

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 6 parameters, an output schema, and sibling tools, the description is complete: it covers input selection rules, output highlights, pagination, size caveats, query behavior, and the relevant prerequisite workflow. The output schema covers the full return shape, so the description does not need to repeat it.

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 already has 100% parameter coverage, so the baseline is 3. The description adds useful context beyond schema details: the protein list is very large, pagination is capped, and the query filter applies specifically to the protein subset. It reinforces the exclusive upid/taxon_id relationship though the schema already states it.

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 starts with a specific verb and resource: 'Fetch the reference proteome for an organism by UPID... or NCBI taxon ID.' It clearly distinguishes this from sibling tools by focusing on proteome-level retrieval rather than individual entries, sequences, or ID mapping.

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 gives explicit usage context: provide exactly one of upid or taxon_id, metadata-only is the common case, proteins are opt-in via include_proteins, and query can be narrowed with a Lucene filter. It also names the prerequisite tool, uniprot_get_taxonomy, for resolving organism names.

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, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond those: the 'cheap sequence-only' cost characterization, the toggle behavior for include_isoforms (alternatively-spliced sequences), and the output shape (length, parsed header). No contradiction with 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?

Four sentences, each earning its place: purpose/outputs, isoform parameter behavior, alternative tool, and input provenance + constraint. Front-loaded with the core action, no filler or repetition of annotation data.

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?

Given an output schema exists (so return format doesn't need restating), full schema coverage, and rich annotations, the description covers everything else: purpose, output components, param toggle, cheaper-vs-fuller alternative, input chain, and a handling caveat. Nothing critical is missing for a 2-param fetch 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 100% — both parameters are fully documented in the schema (accession pattern + canonical-only instruction; include_isoforms default and behavior). The description adds minimal param-level value beyond what the schema provides, so the baseline of 3 applies. The isoform-stripping note is duplicated in schema, not new semantic info.

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?

Uses a specific verb+resource ('Fetch the canonical amino-acid sequence (FASTA) for a UniProtKB accession') and names the exact outputs delivered (sequence, length, parsed header). It explicitly contrasts with uniprot_get_entry ('full functional record'), clearly distinguishing itself from its sibling.

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?

Provides explicit when-to-use guidance ('This is the cheap sequence-only path') and names the alternative for full records (uniprot_get_entry). It also tells the agent where inputs originate (uniprot_search_proteins or uniprot_map_ids) and gives a concrete prerequisite instruction (strip '-N' isoform suffix) before calling.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context: it notes that include_children triggers a separate follow-up lookup (not inline), and that the tool returns a specific set of fields. This goes beyond the annotations without contradicting them.

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 sentences, front-loaded with the primary purpose, and every clause earns its place. It packs essential information (input options, output fields, include_children behavior, and cross-references to sibling tools) without redundancy. No wasted words.

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?

Given the tool's moderate complexity (3 params, output schema present, annotations provided), the description is complete. It covers input constraints, output contents, the optional children behavior, and how it integrates with sibling tools. The output schema exists, so return values don't need elaboration. This is a well-rounded description for the context.

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 all three parameters well. The description adds value by clarifying the mutual exclusivity of name and taxon_id ('provide exactly one') and by explaining the purpose of include_children as a separate lookup. This is slightly above the baseline 3 because it reinforces the constraint and adds context about the follow-up behavior.

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 clearly states the tool resolves a taxonomy record by NCBI taxon ID or scientific name, and lists the returned fields (scientific/common name, mnemonic, rank, parent, lineage). It distinguishes itself from siblings by explicitly mentioning how it feeds into uniprot_search_proteins and uniprot_get_proteome, which is a specific verb+resource+scope.

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 explicitly says to provide exactly one of name or taxon_id, and explains when to use this tool: to turn an organism name into a taxon ID for other tools. It also clarifies that include_children is a separate lookup, not inline, which prevents misuse. This is explicit when-to-use guidance with alternatives named.

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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals that jobs run asynchronously, return 'running' with a ticket or 'finished' with a results page, and support paginated continuation. It also explains the reviewed vs. unreviewed Swiss-Prot/TrEMBL distinction, which materially affects results.

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 dense but every sentence earns its place: core purpose first, then async mechanics, then the reviewed/unreviewed nuance, species disambiguation, and successor tool. It packs substantial guidance into a compact paragraph without redundancy.

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?

The description fully covers the non-obvious workflow: submitting, polling by ticket, fetching continuation pages, and choosing the right target database. Since an output schema exists, the absence of a return-field breakdown is not a gap. This is complete for a complex asynchronous 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?

Although schema coverage is 100%, the description adds crucial operational meaning: which parameters apply only to submission, that ticket and continuation must be passed alone, and that tax_id should accompany Gene_Name. This goes well beyond the schema's per-field descriptions.

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 opens with a specific verb and resource: 'Translate identifiers across databases via UniProt's ID-mapping service,' and gives concrete examples of mappings. This clearly distinguishes it from sibling tools like uniprot_get_entry or uniprot_search_proteins.

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 gives explicit when-to-use context, including the async submission/poll/continuation workflow, when to pass a ticket vs. a continuation, and species disambiguation with tax_id. It also tells the agent to chain results into uniprot_get_entry, which is actionable routing to a sibling tool.

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/openWorld/idempotent, but the description adds substantive behavioral context: the reviewed=true default exists to avoid drowning in ~30x more TrEMBL predictions, paging is forward-only via an opaque cursor with no offset support, and facets produce server-side count breakdowns. This is exactly the kind of value that goes beyond the annotation hints while remaining consistent with them.

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 dense but well-organized: it leads with the core purpose, then covers query modes, filtering defaults, facets, paging, and integration with sibling tools. Every sentence earns its place, and the structured flow from usage to boundaries to follow-up actions makes it easy for an agent to parse.

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?

Given the tool's complexity (8 parameters, two mutually exclusive query modes, server-side facets, cursor pagination, and downstream chaining), the description covers all critical operational behavior while the output schema handles return details. It leaves no major usage question unanswered and explicitly names sibling tools for next steps.

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?

Although the schema has 100% parameter coverage, the description adds complementary semantics: it frames text_search vs query as the 80% case versus the advanced syntax, explains the rationale for the reviewed default, states the exclusivity constraint, and clarifies that organism_id is a convenience filter ANDed onto the query. These are meaning-enriching details not fully derivable from the schema alone.

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 opens with a specific verb+resource: 'Search UniProtKB and return curated protein records.' It clearly distinguishes this tool from siblings by calling it 'the discovery entry point' and explaining that result accessions chain into uniprot_get_entry and uniprot_get_sequence.

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 gives explicit when-to-use guidance: use text_search for the 80% plain-language case, use query for full Lucene syntax, and exactly one is required. It also specifies when to include TrEMBL via reviewed=false, explains cursor paging limitations, and points alternatives for follow-up record retrieval.

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