neumann

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the agent knows this is a real write operation. The description usefully adds that a previously saved Stripe payment method is required and points to GET /billing/pricing for the current per-credit cost, but it omits important financial-safety details such as irreversibility, refund behavior, and idempotency.

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 front-loaded with purpose, then usage context, a pricing pointer, and a minimal example. Every sentence is relevant, though the example sentence is slightly redundant given the schema's existing description of the credits field.

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 a destructive billing tool with rich input-schema descriptions, an output schema, and explicit annotations, the description covers the essential prerequisites: authentication, a saved Stripe payment method, the use case, and where to check pricing. It is not fully complete because it lacks irreversibility or failure-mode context, but it is sufficient for an agent to understand the core invocation.

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 both the api_key and credits parameters are already documented in the input schema. The description adds only a simple example, {"credits":100}, and does not meaningfully enrich parameter semantics beyond what the schema provides.

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 opens with a specific verb and resource: 'Purchases credits using a payment method already saved from a prior Stripe Checkout session.' It is clearly a billing action, not a simulation, estimation, or analysis tool like the siblings, so an agent can distinguish it 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?

It gives clear usage context: use when 'an authenticated account is running low on credits and needs more to keep submitting runs or analyses, without a human re-entering card details.' It does not state when not to use it, but the positive context is explicit enough to route correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is partly covered. The description adds meaningful context the annotations cannot express: it is free and no credits are debited, which is exactly the fact an agent needs before deciding to call it.

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?

Front-loaded with the capability and its outputs, then the usage condition, then the free/no-credit note. The trailing example is long but earns its place by making the nested graph shape concrete; nothing else is padding.

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 two-parameter read-only tool with a full output schema, the description covers what it returns at a high level, when to reach for it, and its cost profile. Nothing an agent needs to call it correctly is missing.

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 100%, so both parameters and the whole graph shape are already documented in structured fields. The worked JSON example is a helpful illustration of graph structure, but it mostly restates what the schema already defines, so the baseline 3 applies.

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 ('Pre-flight-sizes') and resource ('a graph'), and enumerates the concrete outputs: peak memory, engine complexity, tier, credit cost. It also draws the explicit contrast with run_simulation by saying 'without running it', so the agent can tell this apart from its heavier sibling.

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?

Gives a clear when: 'when you want to know what a run will cost or how heavy it is before committing', with a qualifier for large or unfamiliar graphs. It does not explicitly name alternatives such as validate_graph or run_simulation, so the routing is implied rather than spelled out.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description adds that the message goes to a human team, that a copy is CC'd to sender_email, and that anonymous submissions are allowed. It doesn't discuss rate limits or what happens on failure, but the human-destination and CC behavior is real context beyond the 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?

Purpose and trigger condition are front-loaded, and the closing example earns its space by showing the shape of a valid call. It is slightly long with a bit of overlap between 'straight to the Neumann team' and 'a human to see it directly'.

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?

Output schema and full parameter descriptions exist, so the description needn't explain return values; it covers destination, copy semantics, and usage context. One minor tension: it claims 'anonymous submissions are allowed' while sender_email is a required field, which an agent may find confusing.

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; the description goes further by showing a full worked example payload that demonstrates the feedback_type/message/sender_email combination in practice. It also restates the CC behavior of sender_email, which reinforces the schema's meaning.

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?

Names a specific verb and resource ('Sends feedback, a feature request, or a bug report') and names the destination ('straight to the Neumann team'). No sibling tool overlaps, so an agent can select it unambiguously.

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?

Gives a clear trigger condition — 'when something about the service is wrong, missing, or confusing and you want a human to see it directly rather than guessing at a workaround'. That arguably steers the agent away from the simulation/results siblings, though it never names an alternative explicitly.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: returns status first and the result only 'once available', so a caller knows a partial/not-ready response is possible, plus the contrast with run_simulation's blocking semantics. It stops short of covering error cases for an unknown run_id or any retention/expiry behavior, so not a 5.

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?

Purpose is front-loaded in the first clause, and the usage caveat follows immediately. Slightly padded: the JSON example largely restates the one-parameter schema, and the run_simulation caveat is packed into a long parenthetical that takes a second read.

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?

With an output schema present, return values need not be described; annotations cover safety; the single parameter is fully documented. The description supplies exactly the missing pieces — when to call it and that results may not yet be available — leaving no gap an agent needs to close before invoking it.

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 100% and the single run_id parameter is documented as 'A run id returned by run_simulation'. The description's example call shows the ID's string shape, which is marginally additive, but otherwise the schema carries the load — the baseline 3 applies.

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 ('Fetches the status and ... the summarised result for a previously-submitted run by its run_id') and explicitly distinguishes itself from run_simulation, the sibling an agent would otherwise confuse it with. The scope — retrieve an existing run, no resubmission — is 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?

Gives both the positive case ('re-check or re-fetch a run you already submitted') and the exclusion ('run_simulation itself already blocks until done ... so this is not a poll-until-ready step for it'). That is an explicit when-to-use plus a named alternative and its disqualifying condition.

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

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

Annotations already fix the safety profile (not read-only, not destructive, closed-world), so the description's job is to add context. It adds the billing behavior ('Debits one credit for authenticated callers'), which the annotations do not carry, and describes the perturbation methodology. It stops short of runtime cost or expected latency, but for a non-destructive analysis call this is solid 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?

Front-loaded with the mechanism, then the when-to-use, then billing, then a concrete example — a sensible ordering with no filler. The embedded JSON example is long relative to the prose but earns its space for a graph-shaped payload.

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 7-parameter tool with one required argument and a full output schema, the agent has enough: it knows the analysis type, what is swept, what baseline means, the target node default behavior via schema, and the credit cost. Only the boundary against sibling analysis tools is left implicit.

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% and the schema is heavily documented (quantiles, num_quantiles exclusivity, time_period default, target_node_id default all spelled out), so the baseline is 3. The example concretizes the graph shape (root node distribution params, calc node formula, edge wiring, run_params), which helps, but the tool-specific knobs are covered only by the schema, not the prose.

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 analysis type ('runs a one-at-a-time tornado sensitivity analysis') and then explains the mechanism: sweeping each root node over quantiles with others held at baseline, ranking by impact on the target node. That mechanism-level detail distinguishes it from siblings like scenario_analysis, estimate, and run_simulation without the agent opening any 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?

Gives a clear decision rule: 'Use this when you need to know which uncertain input most drives an outcome, so you know what to de-risk or estimate more carefully first.' That is a real when-to-use signal, but it never names the sibling analyses (scenario_analysis, estimate) or states when this tool is the wrong choice, so the agent must infer the boundary itself.

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

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

Adds genuine information beyond the annotations: it will not return a run_id to poll and completes synchronously in the same call, and it returns a full distribution rather than a summary point. What's left unexplained is the "both tiers" reference — the two execution paths (inline vs. large) are never defined, and no cost/credit or size-limit behavior is mentioned in the description.

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?

Front-loaded: purpose, then usage condition, then the synchronous-result guarantee, then an example. Every sentence earns its place. The single large JSON example is justified for a deeply nested input, though the unexplained "both tiers" phrase is filler that could be cut or clarified.

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?

With an output schema present, return values need no explanation, and the input schema fully documents the graph. The description covers purpose, selection criteria, and execution semantics. Gaps are minor: the tiers are undefined and credit consumption is only visible in the api_key schema field, not the description.

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 100% and the nested graph types are documented in depth, so the baseline is 3. The worked example does add concrete shape (root distribution params, formula edge ids, run_params), but it reillustrates rather than explaining anything the schema doesn't already state.

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?

Names a specific verb and resource ("Runs a Monte Carlo simulation") and immediately states what it is over ("a graph of probabilistic root and calculated nodes"). The contrast with "one guessed number" implicitly separates it from the point-estimate sibling, so an agent can tell what it produces 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?

Explicitly says when to use it: "when you need the range and likelihood of outcomes for a plan driven by uncertain inputs, not just its average case." That condition does the routing work against estimate/solve_distribution_parameters. It stops short of naming those alternatives or stating when not to use it (e.g. validating a graph first).

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the description usefully adds that the call 'Debits one credit for authenticated callers' and that it performs exactly one simulation run (not a distribution sweep). It also discloses an output trait beyond the schema ('each paired with a best-effort driving input per root node'), notably that the driver attribution is heuristic. It stops short of stating what happens when credits are exhausted or how failures are surfaced.

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 core statement and the usage condition are front-loaded in the first two sentences, and the credit cost is placed before the example where it is visible. The trailing JSON example is long but pays for itself as a construction template; a slightly tighter opening sentence would be ideal.

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?

An output schema exists, so return values need not be explained, and the nested graph schema is richly documented on its own. The description covers purpose, selection condition, cost and a concrete input example, leaving only edge cases (anonymous/free path, credit exhaustion, failure modes) unaddressed.

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; the description earns above that by supplying a complete worked graph example showing root_nodes, calc_nodes, edges and run_params together, which materially helps construct the one required parameter. It also reiterates the percentile semantics (worst/median/best) in plain terms, though it adds nothing about seed or time_period beyond the schema.

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 ('Runs a simulation once and summarises a target node's worst/median/best outcomes'), including that arbitrary percentiles are supported. It also implicitly distinguishes itself from the full-distribution sibling by contrasting 'a quick worst-case/median/best-case narrative' with 'the full distribution', so an agent can route between this and run_simulation without opening either 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?

Explicitly gives the selecting condition: 'Use this when you need a quick worst-case/median/best-case narrative for a plan rather than the full distribution.' That is a clear when-to-use with an implied alternative, but it never names run_simulation or get_results, so the agent must infer the sibling by name rather than being routed to it.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description goes well beyond them by disclosing idempotent create-or-fetch behavior, the split auth model (credential required to create, none required to view the resulting share_url), and the renderable output formats. It does not cover link expiry, revocation, or rate limits, so it stops short of a 5.

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?

Front-loaded with the core action, then constraints, then auth, then an example — a sensible ordering with no filler sentences. Minor waste: the stored-graph/persisted constraint is asserted twice and the example JSON largely duplicates what the schema already declares.

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?

An output schema exists, so return values need no explanation, and every other agent-relevant fact is present: required persistence precondition, auth path, credential-free viewing, and supported render formats. Nothing needed to call it correctly is missing.

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 100%, so a 3 is the floor; the description adds genuine meaning by explaining why run_id must be persisted (ephemeral run_simulation ids are unusable) and by restating the api_key-vs-Bearer alternative. The inline example reinforces the required argument shape but adds little the schema does not already say.

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 ('Creates (or fetches the existing) public share link for a PERSISTED run') and immediately names the sibling it must not be confused with (run_simulation). An agent can distinguish it from get_results or run_simulation without opening any 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?

Gives an explicit when-to-use ('when you want to hand a result to someone without giving them API access') plus an explicit exclusion ('only for a run saved via the stored-graph flow: a run_simulation result is ephemeral and has no usable run_id'). That is exactly the routing information an agent needs versus the sibling run tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false; the description adds non-obvious operational context beyond them, namely 'Free; no credits debited', which matters given the sibling buy_credits. It doesn't discuss failure modes for invalid distribution types, but the output schema covers return shape.

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?

Three short sentences plus a compact JSON example, with the purpose front-loaded before the usage condition and the cost note. The example slightly restates what the schema already documents, keeping it just short of maximally efficient.

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?

With a full schema, complete annotations, and an output schema, the description covers purpose, cost, and a canonical invocation example. It leaves the mapping from distribution_type to which estimate fields are required to the schema, which is acceptable given the schema's per-field descriptions.

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 worked example adds meaning by showing how distribution_type, min_estimate, max_estimate, and percentile_range combine into one coherent call. It also verbally maps 'most-likely value' to mode_estimate, clarifying an otherwise ambiguous field name.

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 a specific verb ('Converts') and a specific resource ('a human-style estimate ... into the distribution_params a root node needs'), which is a transformation distinct from siblings like estimate or run_simulation. The example input makes the scope unambiguous 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?

It explicitly states the trigger condition: 'Use this when you have a rough verbal estimate like "between 80 and 120, 90% confident" and need engine-ready parameters rather than guessing them yourself.' That is clear positive guidance, but no when-not-to-use or explicit alternative sibling is named (e.g. when to prefer estimate or run_simulation instead).

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

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

Adds real context beyond the readOnlyHint/destructiveHint=false annotations: that validation is free and no credits are debited, and that the result is a list of issues classified by rule and severity. It does not explain whether validation is enforced before a run or how severity should be acted on, keeping it below 5.

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 two lead sentences are tight and front-load the purpose, usage condition, and cost. The trailing example is long and partially redundant with the schema's $defs, which dilutes an otherwise efficient description.

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?

With an output schema present, the description needn't detail return values, and annotations cover the safety profile; the description fills in cost and trigger conditions well. Minor gap: the meaning and handling of 'severity' levels is left unexplained.

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 100%, so the schema already documents both parameters; the description goes further with a concrete worked example of a valid graph shape. It offers no guidance on the optional api_key beyond what the schema states.

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?

Uses a specific verb ('checks a graph') with an enumerated set of what it looks for (cycles, dangling edges, unknown distributions, missing refs) and a stated output shape (issues by rule and severity). It is clearly distinguishable from run_simulation, which actually executes the graph.

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?

Explicitly states when to use it: 'when you built or edited a graph by hand and want to catch mistakes before spending a run on it,' which implicitly routes the agent away from run_simulation. No explicit when-not or mention of the estimate/run_simulation alternatives by name, so it falls short of a 5.

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