ebi-pdbe-ent_iface_res_ent_iface_res_id_e3f93cbf

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description need only add context — which it does by describing the computational source (PISA) and the shape of the payload. It stops short of disclosing volume, pagination, or whether all interfaces are returned when no filter is given, which matters for a potentially large contact list; also idempotentHint=false is unexplained but not contradicted.

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 sentences, front-loaded with purpose followed by return content and filtering options; no filler or repetition. It could be tightened slightly, but every sentence contributes information an agent would use.

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 no output schema, the description carries the burden of describing return values and does so adequately at a field level (interaction types, distances, atoms and residues from both chains). The remaining gap is scale — nothing about result size or whether the call is paginated for a PDB entry with many interfaces.

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 coverage is 100% and each parameter is already documented, so the baseline is 3; however the description adds real meaning by stating that assembly_id and interface_id are optional filters and that filtering narrows the returned contacts, which the schema text ('Numerical assembly id code', 'Index of interface, one based') does not convey on its own.

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 — 'Returns all interface residue contacts calculated by PISA' — scoped to 'a specified PDB entry ID', and it enumerates the returned content (interaction types, distances, participating atoms/residues). It does not explicitly differentiate itself from the closest sibling, ebi-pdbe-iface_res_ent_interfaces_id_entity_id (entity-level interface residues), so an agent must infer the distinction from 'contacts' vs 'interfaces'.

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 only implied: the tool is for retrieving PISA-calculated contact detail for a PDB entry, and the sentence 'Results can optionally be filtered by assembly_id and interface_id' hints at when to supply the optional parameters. There is no explicit when-to-use / when-not-to-use guidance and no naming of alternatives such as the entity-level interface residues tool.

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