robot_rename

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

No annotations are provided, so the description carries full behavioral disclosure burden. It mentions three mapping modes but does not disclose side effects (e.g., in-place modification), required output, permissions, or failure modes. Parameters like allow_missing_entities and allow_duplicates are not explained, leaving behavioral traits unclear.

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 a single paragraph of moderate length. It front-loads the purpose and then lists mapping options. However, it could be more concise or better structured (e.g., bullet points for mapping methods). Every sentence is relevant, but some information is repeated.

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 16 parameters and many undocumented, the description is incomplete. The output schema exists but its contents are not described; return values and error conditions are omitted. Important parameters like allow_missing_entities and allow_duplicates lack explanation. The description covers only the core renaming modes, missing much context needed for effective tool use.

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 0%, so the description must compensate. It explains mapping, mappings, and prefix_mappings, but neglects 13 other parameters including input, output, allow_missing_entities, and working_directory. The description adds meaning for only a fraction of the parameters, leaving most undocumented.

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 clearly states 'Rename entity IRIs via full replacement or prefix-based renaming' with verb and resource. It lists three mapping methods (mapping, mappings, prefix_mappings), distinguishing it from sibling tools like robot_annotate. However, it does not specify the type of entities (e.g., ontology entities) or the input format.

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?

Description provides explicit usage for each mapping parameter: 'Use mapping for individual IRI replacements... Use mappings to point to a TSV file... Use prefix_mappings for bulk prefix replacement.' This helps the agent choose the right parameter. It does not explicitly state when not to use the tool or compare to alternatives, but the guidance is clear for the tool's own parameters.

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