ebi-pdbe-ligand-interactions

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

Annotations already establish readOnly/openWorld/non-destructive, yet the description adds real behavioral context beyond them: records are PDBe-supplied, distances and classifications are displayed without recalculation or reclassification, and contact lines are suppressed when atom/assembly mapping is ambiguous with a fallback to 'the table'. That conditional-suppression behavior is exactly the kind of disclosure an agent cannot get from annotations. It would be a 5 if it were clearer about what permissions or payload volume to expect.

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 purpose then procedure, with no filler sentences. A few phrases ('supplied interaction records', 'use the table') are terse enough to be slightly ambiguous, but nothing is redundant.

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 six parameters, no output schema, and no field documentation in the schema, the description carries most of the burden and does explain the two-phase flow and the content of returned records (classifications, distances, contact lines). Gaps remain: it references 'the table' without explaining it and never characterizes the shape or volume of the returned interaction list.

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%, so the description must compensate, and it largely does: it explains that pdb_id triggers instance listing, and that auth_asym_id/auth_seq_id/comp_id/insertion_code together identify a specific instance, including that CCD and insertion code are optional ('when available'). Only label_asym_id is left entirely unexplained, which keeps it from a 5.

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 — PDBe-reported ligand interactions for an exact ligand instance — and distinguishes itself from generic search tools by scoping to 'exact ligand instance'. However, it never explicitly names the closely related siblings (comp_intx_proteins, comp_intx_hetcode, ligand_sum), so the agent must infer the boundary from the two-step instance workflow.

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 an explicit staged usage instruction: first call with a PDB ID to list instances, then supply author chain and author residue number (plus CCD and insertion code when available) to fetch that instance's records. That is clear sequencing guidance. It falls short of a 5 because it never states when NOT to use this tool or which sibling to pick instead for non-instance-level interaction data.

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