create_correspondent

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

No annotations are provided, so the description carries the full behavioral burden. For a mutation tool it says nothing about permissions, name-uniqueness/duplicate handling, idempotency, or what is returned after creation. It only hints that match/matching_algorithm drive automatic document assignment, which is useful but thin.

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?

One well-formed sentence with the core action front-loaded and no filler. It is appropriately sized, though it stops short of adding any operational detail.

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 simple 3-parameter create tool with no output schema and no annotations, the description covers the action and the optional fields' intent. It leaves gaps on return value and on how the matching fields interact with existing documents, which matters given the tool's stated purpose of automatic assignment.

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 33% – only matching_algorithm is documented in the schema, and it is documented exhaustively (0-6 enum meanings). The description compensates partially by explaining that 'match' is a pattern and 'matching_algorithm' governs automatic assignment, but it does not clarify match syntax (regex vs. plain) despite algorithm 4 being regex.

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?

States a specific verb and resource ('Create a new correspondent') and adds the purpose of the optional fields ('matching pattern and algorithm for automatic document assignment'). An agent can tell it apart from get_correspondent/update_correspondent by name, but the description does not explicitly contrast it with those siblings.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The only implied usage is the verb 'create', and there is no mention of update_correspondent for existing records or list_correspondents for lookup.

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