calculate_divergence

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the mathematical operation and includes an example showing the return value. However, it doesn't mention error conditions (e.g., what happens with invalid vector_field_key), performance characteristics, or side effects (e.g., whether it modifies state). The example helps but leaves behavioral gaps.

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 well-structured and appropriately sized. It starts with a clear purpose statement, provides parameter documentation, includes a practical example with workflow context, and specifies the return value. Every sentence adds value without redundancy, and the example is directly relevant to tool usage.

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 mathematical nature, single parameter, and lack of output schema, the description is quite complete. It explains what the tool does, how to use it with an example, and what it returns. However, it doesn't cover edge cases or error handling, which would be helpful for a computational tool. The example provides good context but doesn't make it fully comprehensive.

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 description adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'vector_field_key' refers to 'The key of the vector field expression' and shows in the example how this key is obtained from create_vector_field. This clarifies the parameter's purpose and expected format, compensating well for the schema's lack of documentation.

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's purpose: 'Calculates the divergence of a vector field using SymPy's divergence function.' It specifies the exact mathematical operation (divergence calculation), the resource (vector field), and the implementation method (SymPy). This distinguishes it from siblings like calculate_curl or calculate_gradient, which perform different vector calculus operations.

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 clear context through the example, showing that this tool should be used after creating a coordinate system and vector field. However, it doesn't explicitly state when NOT to use it or name alternatives (like calculate_curl for curl operations). The example implies a workflow but lacks explicit exclusion guidance.

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