nv_probe

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

With no annotations, the description carries the full burden. It discloses that free-tier keys may yield 404s, that the probe tests one category at a time or all, and that timeout_seconds is a per-model deadline. This provides useful behavioral context without repeating schema info. It could mention that the tool is read-only, but 'test' implies no side effects, and the 404 caveat is strong added value.

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 compact and well-structured: a one-sentence purpose, a brief context paragraph, and an args list. Every sentence adds value. It is front-loaded with the core action and uses formatting for readability, with no fluff or repetition.

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 there is an output schema (not shown), the description doesn't need to explain return values. It covers purpose, usage context, and both parameters sufficiently. It does not discuss error handling beyond the 404 note, but the timeout and category scope suffice for a probing tool. Overall, it is complete for its complexity and sibling set.

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 input schema has no descriptions (0% coverage), so the description must explain parameters. It does: 'category: probe one category only (e.g. "vision"). Empty probes them all' and 'timeout_seconds: per-model deadline.' This clarifies the empty default and the scalar meaning, going beyond the bare schema. It doesn't list valid categories, but that is a minor gap given the sibling nv_categories.

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: 'Test which models actually answer on THIS account, and how fast.' It distinguishes itself from the catalog-listing sibling (nv_list_models) by focusing on actual servability and ground truth. The verb 'test' plus resource 'models' is specific and unambiguous.

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 context for when to use the tool: 'Being listed by the catalog endpoint does not mean a model is servable... Run this to get ground truth.' This implies it is the follow-up to nv_list_models when you need reliable availability. It also notes free-tier key behavior, giving clear situational guidance. It doesn't explicitly name alternatives but the catalog endpoint reference covers that.

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