Prime number tools

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds meaningful behavioral context beyond that: deterministic Miller-Rabin below 2^64 but probabilistic above, Pollard rho for factorisation, and hard input limits. The probabilistic-result caveat is exactly the kind of correctness detail an agent needs and cannot get from annotations.

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?

It is front-loaded with the overarching purpose and then structured by mode, and nearly every clause carries information. It is a dense single paragraph and the trailing website URL plus 'like the website' are marginal, but there is little true filler.

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 six-parameter, three-mode tool with no output schema, the description covers the mode semantics and hard limits well. It does not describe the shape of returned results (e.g., factorisation format or how gcd steps are returned), which would matter without an output schema, so it falls short of a 5.

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%, so the baseline is 3, but the description adds real semantics: check accepts expressions like '2^61-1' or '10!+1' up to 400 digits, gcd_lcm takes 2–50 numbers, and range is bounded below 10^15. It omits the 'limit' parameter's 100,000 cap and exact-count behavior, so not 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 the resource ('number theory with big integers') and enumerates the three modes and exactly what each computes: primality, factorisation, divisor counts/sums, φ, prev/next prime, perfect, gcd/lcm, and prime ranges. This lets an agent distinguish it from siblings like calc_expression or calc_fraction without opening the schema.

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 mode list clearly implies when each mode applies, and it names constraints (400-digit expressions, ranges below 10^15, 2–50 numbers for gcd_lcm, max 10,000,000 numbers per range). It does not explicitly name alternatives or exclusions (e.g., use calc_expression for plain arithmetic), which is the one missing piece.

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