OwlCAD

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'It changes NOTHING: no project is read or written.' Beyond that it adds non-annotation context: Pro plan requirement, the `ask` scope, a shared daily allowance, and that an empty answer signals a documentation gap rather than an error.

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 what the tool does before caveats, and each sentence carries useful information. Slightly long and the 'It changes NOTHING: no project is read or written' clause partially restates the readOnly annotation, but it's a worthwhile emphasis rather than 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?

With no output schema, the description must explain returns — it does: prose answer, source article ids, and that an empty answer is informative. Access requirements (Pro plan, `ask` scope, shared quota) are also covered, so nothing needed to call this 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 locale, history, and question are already fully documented in the schema. The description adds only a slight framing point ('in plain language') and does not extend parameter meaning beyond what is structured. Baseline 3 is appropriate.

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 (ask) and resource (OwlCAD documentation) and precisely characterizes the output: a prose answer grounded in the docs plus the ids of the articles used. This clearly separates it from action siblings like evaluate, measure, or check_interference, which perform work rather than answer questions.

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 to know which tool or parameter does a thing') and gives two concrete example questions. It also names the alternative — 'prefer the schema resources for anything they already answer' — which is exactly the routing information an agent needs.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful framing (interferences are usually hidden inside the model, so neither tree reasoning nor rendering catches them), but says nothing about runtime cost, the smoothness/threshold trade-offs invoked by the schema, or what the result looks like. Adequate, not rich.

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?

Two sentences, tightly front-loaded with the outcome first and the rationale second. Every clause carries information; nothing 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 read-only check with atomically-documented parameters and safety annotations, the description covers purpose, applicability, and the conceptual form of the answer (which parts, how much volume). With no output schema present, it could say a bit more about the shape of the returned results (per-pair list vs summary), but nothing essential to correct invocation 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 the schema already documents scad/nodes/projectId, smoothness and minVolumeMm3 in detail. The description's mention of 'top-level parts' and 'by how much volume' loosely gestures at scoping and the volume threshold but adds no syntax or constraint beyond what the schema states. 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: find top-level parts that physically overlap and quantify the overlap volume. It also distinguishes itself from the two obvious competing approaches (reasoning about the node tree, inspecting a render), which is what makes the tool's role unambiguous among siblings like measure, render and print_check.

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?

"Run it on anything with more than one part that is meant to fit together" gives a clear positive trigger and implicitly excludes single-part models. It does not, however, explicitly say how it differs from or when to prefer it over neighboring checks such as print_check or measure, so one inference step remains.

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 write/idempotency profile; the description adds the operational traits that matter: two distinct expiries (uploadUrl in minutes vs ticket in a day), the required PUT-then-import sequencing, the browser handoff path, and polling until the importer stops returning 'awaiting_upload'. This is substantially more than the structured fields convey.

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 token-cost rationale and the core instruction (PUT to uploadUrl, then call the importer with ticketId) are front-loaded, and the fallback and expiry caveats follow in priority order. Dense but no sentence is 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?

With no output schema, the description carries the return-value burden and does so: uploadUrl, headers, ticketId, and handoffUrl are all explained, along with the follow-up polling behavior. Nothing an agent needs to complete the upload flow 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 coverage is 100%, so the baseline is 3, but the description adds workflow meaning on top: ticketId is framed as a re-issue handle ('pass ticketId back here for a fresh URL rather than starting over'), and it explains the non-input values uploadUrl and headers that the schema cannot cover. Format's 'required unless refreshing' nuance is reinforced in context.

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 ('get a URL to PUT a local file to') and names the downstream consumers (import_model, import_2d), which distinguishes it from every sibling importer. An agent immediately knows this is the pre-step that avoids shipping bytes through context.

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?

Explicit when-to-use (before import_model/import_2d, to avoid base64 token cost), explicit fallback (handoffUrl when the agent cannot PUT), and explicit recovery path (pass ticketId back for a fresh URL rather than restarting). Alternatives and conditions are all named.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description still adds value by disclosing that deletion is permanent with no trash/recovery and that geometry is cascaded, plus an ownership restriction. It does not say what happens to shared or referenced projects, but the core destructive behavior is well disclosed.

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?

Two short sentences, zero filler, with the permanence warning front-loaded immediately after the action statement. Nothing to trim.

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 single-parameter destructive tool with no output schema and annotations covering the safety profile, the description covers everything needed: what is deleted (project + geometry), irreversibility, and the ownership gate.

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% for the single projectId parameter, so the schema already documents it. The description's 'one you created' constraint reinforces the ownership rule but adds no format or identifier detail beyond the schema, matching the baseline for a fully documented 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 (permanently delete) and resource (a project plus its geometry), with scope spelled out so an agent can separate it from edit_project, organize_project, and share_project. No ambiguity about what is removed.

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 concrete when-not rule — 'Deleting a project you did not create is not possible' — which tells the agent an ownership precondition exists. It stops short of naming alternatives such as edit_project for non-destructive changes, so it is context rather than full routing guidance.

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, idempotentHint, destructiveHint), and the description goes well beyond them: it discloses that unresolvable ops are skipped and reported in `skipped` rather than failing the call, that tree-shape losses surface in `treeWarnings`, and that node ids are preserved or auto-assigned so later calls can reference them. That is real behavioural context an agent cannot get from the structured fields.

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 purpose and the nothing-is-saved guarantee in the first two clauses, and every sentence carries information that is not duplicated elsewhere. It is dense and long-tailed for a two-parameter tool, with the id/forgiving sentences packed into many clauses, but little is genuinely wasted.

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?

There is no output schema, so the description correctly explains what comes back (`skipped`, `treeWarnings`, ids assigned to unnamed nodes) and delegates the op vocabulary and placement arithmetic to resources. For a tool whose real complexity lives in a referenced schema, this is complete enough to call correctly.

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%, but the critical `ops` array has no item schema at all, and the description fills that structural gap by pointing to owlcad://schema/edit-ops and owlcad://schema/primitives. It also adds id-retention semantics ('a node you send keeps the id you gave it, and one you omit an id for gets one back') that the schema does not express.

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 ('Apply edit ops to a node tree you pass IN, and get the edited tree back') and immediately scopes it as 'the unsaved counterpart to edit_project', so the agent can tell it apart from its closest sibling 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 names the alternative (edit_project) and the condition that selects this one: use it to change a model 'you are still working on without re-sending the whole tree every time', then feed the result to evaluate, print_check or export. The saved-vs-unsaved distinction is stated outright rather than left to inference.

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?

The description adds substantial behavioral details beyond annotations: it states the call is transactional ('Every op must apply or the whole call is refused and nothing is written'), describes restructuring capabilities (dissolve a boolean, unwrap a modifier, turn a selection into a component), and mentions a node cap. These are crucial traits for a mutation tool with destructiveHint=true.

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 the core purpose and key differentiators, then covers transactional behavior, restructuring capabilities, and schema references. Every sentence carries unique value and there is no redundancy.

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 complexity (24 different ops within an array parameter, nested objects, and destructive nature), the description is complete enough: it orients the agent to the scope, points to the detailed schema resource, and explains the transactional model and restructuring powers. No output schema is needed.

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 itself contains rich descriptions for every field. The description adds some high-level meaning (e.g., 'owlcad://schema/edit-ops lists what every op requires; the schema below is a flat bag of every field any op takes') but does not provide per-parameter detail beyond what the schema already offers. Baseline 3 is appropriate when the schema is comprehensive.

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 uses a specific verb+resource ('Make a TARGETED change to one of your projects') and enumerates the kinds of changes (change a parameter, move a node, add or remove one, group nodes, create or set a variable, switch configuration). It also explicitly distinguishes this tool from sibling update_project, making it easy to tell apart.

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 explicit when-to-use guidance ('Prefer this over update_project when you are changing an existing model') and a prerequisite ('Read with get_project `authored: true` first'). It also alerts the agent to important alternatives and preconditions, leaving little to inference.

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 (readOnly, idempotent, non-destructive), yet the description goes further: it scopes what `warning` actually checks (bounding-box sanity only) and what it explicitly does NOT cover (overhangs, wall thickness), and discloses that unbuildable nodes are silently dropped or changed and surfaced in `treeWarnings`. That is genuinely useful behavioral 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?

Front-loaded with the core purpose and return shape, then usage, then caveats, with no filler sentences. It is dense for a four-parameter tool, but each clause (warning scope, treeWarnings behavior, alternative tools) carries distinct information.

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?

There is no output schema, but the description effectively describes the return contents (build status, watertightness, triangle count, bounding size, warning, treeWarnings), so an agent knows what to expect. Combined with the companion-tool routing, nothing needed to invoke 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 the schema already documents scad, nodes, projectId and smoothness in detail. The description adds little parameter-level syntax or default information on top of that; baseline 3 is appropriate when the schema carries the load.

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 outcome: run a model through the real CSG kernel and report whether it BUILDS, naming the exact signals returned (watertight, triangle count, bounding size in mm). It clearly distinguishes itself from print_check and measure, so an agent can route correctly 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?

Explicitly says when to call it ('before exporting') and names the alternatives with their conditions: print_check for printability, measure for material. It also explains the empty-result symptom (boolean operands did not overlap) so the agent knows what a failure implies.

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?

Despite annotations, the description adds substantial non-obvious behavior: 3MF is CARVED into one named, coloured object per top-level part with names returned in `objects`, STL is a single fused mesh, inline base64 is context-capped, and `deliver: url` writes to the account and yields a 24h link. These are real operational facts not derivable from 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?

Front-loaded with the core action, then format nuances, then the STEP routing caveat — a sensible order with little waste. It is slightly dense in the middle clause about carving, but every sentence carries information.

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 no output schema, the description carries the return-value burden and does so: base64 bytes, the `objects` list for 3MF, and the inline-vs-URL delivery tradeoff with caps and expiry. An agent has everything needed to call it and interpret the result.

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 still adds meaning beyond the schema: the 3MF-vs-STL structural difference, the `objects` name list, and the note that STEP is handled by a different tool (a format not in the enum). It duplicates some of the `format` field's own text, keeping it from 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?

Opens with a concrete verb+resource ('Evaluate a model and return it as base64 bytes in STL, 3MF or OBJ'), so the agent immediately knows what it produces. It also distinguishes itself from siblings by explicitly naming export_step as the B-rep/STEP path, separating mesh export from the other export tools.

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 a clear routing rule for the nearest alternative ('For STEP use export_step — it is B-rep, takes minutes, and runs as a job') and advises `deliver: url` for large output or handing a file to a person. It does not, however, address export_2d or when to prefer this over evaluate/render, so guidance is strong but not exhaustive.

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=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful behavioral context about what section mode reveals, but it does not disclose account file writing, inline size caps, or other export side effects covered only by schema parameters.

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?

Two sentences, front-loaded with the core action. Every clause earns its place by clarifying output formats, use cases, or mode behavior; no redundant restatement of the name or schema.

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 12-parameter export tool with a rich input schema and no output schema, the description adequately covers the core flattening behavior and the critical mode distinction. Details like model input selection and return delivery are left to the detailed schema, so the description is complete enough but not exhaustive.

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 baseline is 3. The description adds interpretive meaning beyond the schema for mode (silhouette projects to the view plane; section cuts through for internal inspections) and implies format choice for different machines.

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: flatten the model to 2D as DXF or SVG. It clearly distinguishes itself from 3D export siblings like export_step by emphasizing 2D output formats and fabrication use cases.

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 clear context (laser, vinyl cutter, CNC) and explains the two mode choices: silhouette for projection, section for cutting through and checking hidden internal features. It does not explicitly compare itself to export or export_step, so it stops short of full alternative guidance.

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 declare this is not read-only, not idempotent, and not destructive, but the description adds substantial behavioral context beyond them: OCCT processing takes minutes, the call returns a jobId rather than the finished file, polling must wait retryAfterMs, waitingMs is reported, and Pro accounts are required. It also clarifies that a still-queued job after a few minutes is stuck and should be abandoned rather than polled endlessly.

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 dense but front-loaded with the core purpose and then proceeds through prerequisites, job lifecycle, polling rules, and edge cases. Every sentence carries operationally necessary information, and no space is wasted on restating the name or schema.

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 beta async export tool with no output schema, the definition covers what the agent needs: prerequisite project state, Pro account requirement, job creation and polling mechanics, retry timing, stuck-job detection, and the difference between B-rep and mesh export. Nothing essential 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 the baseline is 3. The description adds valuable semantics beyond the schema by explaining the projectId/jobId lifecycle: projectId is used to start the job, jobId is used alone to poll, and the two should not be combined during polling. It does not elaborate fit or keepFacets, but the schema already documents those thoroughly.

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: 'Export a SAVED project as STEP (beta) — real B-rep, not a mesh, for CAD interchange.' It distinguishes itself from generic export siblings by naming the format and clarifying it is not a mesh export, so an agent can tell it apart immediately.

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 describes the two-phase async workflow: call with projectId to get a jobId, then poll with jobId alone until status is 'done'. It names the prerequisite (save_project first), states that it cannot export an inline tree, warns about polling budget, and gives a stop condition for stuck queued jobs. This is thorough when/when-not guidance.

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, idempotent, non-destructive), so the description's added value is the return-content inventory and the warning that the authored form is what you should write back. It stops short of describing result shape or size, but it goes meaningfully beyond what the annotations declare.

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 sentences, no filler, with the core action front-loaded and the write-back caveat at the end where it belongs. Slightly dense on the em-dash enumeration, but every clause carries information.

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 no output schema, the description compensates by naming what is returned (nodes, variables, components, configurations, mates). Combined with rich annotations and full schema coverage, an agent has enough to call it correctly; only return format/size details are absent, which is a minor gap for a read tool.

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 authored property's schema text already explains stored vs resolved, instance expansion, mate solving and suppressed configurations in detail. The description only echoes the 'use true before changing' rule, adding little beyond the schema, 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?

It states a specific verb ('Load') and resource ('a project') and enumerates what comes back: nodes with parameters, plus variables, components, configurations and mates. The stated context ('inspecting or describing an existing model') helps, though it doesn't explicitly differentiate itself from siblings like evaluate or list_projects.

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?

'For inspecting or describing an existing model' implies the read use case, and the closing line gives a when-to-do-what rule ('Pass authored: true before you intend to CHANGE it'). However, no sibling alternative is named or excluded, so the agent must infer that list_projects or evaluate are different 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 write/openWorld/non-idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond them: the result is parametric (each closed outline becomes an editable `extrude` node) and the response reports declared units and unread entity types — meaningful disclosure for a tool with no output schema.

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 sentences, front-loaded with the action and result, and each sentence carries information. The rhetorical aside ('a drawing someone sent you becomes a model you can change') is slightly verbose but still clarifies the parametric payoff.

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 mutation tool with annotations covering safety and no output schema, the description supplies the parametric behavior and the key return contents (declared units, unread entity types). It omits failure behavior and size limits, but those are largely covered in the schema.

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% with 6 well-documented parameters, so the schema carries parameter meaning. The description only indirectly touches semantics by mentioning the reported unit, which relates to unitFactor, adding little beyond the schema's own guidance.

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+resource+outcome: import a DXF as a new project extruded into solid geometry, and explicitly contrasts with mesh import to distinguish it from the sibling import_model. An agent can tell exactly what this produces without reading 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 contrast with mesh import gives clear selection context (parametric vs. static geometry), and the schema steers callers with on-disk files to create_upload. However, no sibling is named directly and there is no explicit when-not guidance beyond the mesh contrast.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial behavior context beyond them: unit guessing and reporting, the watertightness report, and the crucial note that `repair` moves geometry and defaults off. This meaningfully informs invocation strategy.

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 sentences, front-loaded with the purpose and formats, and each sentence carries actionable content (unit handling, watertightness consequence, repair workflow). It is dense but no sentence is pure filler; the final sentence is slightly overloaded.

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 no output schema and 7 optional parameters, the description does the necessary work of explaining the return signals (unit guess, watertightness). It covers the key decision points for a complex import tool, though it omits error/failure modes and how it relates to the create_upload/import_2d siblings.

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 and the schema already documents every parameter richly. The description adds format-specific meaning not in the schema — that STL and OBJ carry no unit and the guess is reported back — which marginally raises it above baseline.

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 (import) and resource (STL/OBJ/3MF mesh file) and adds scope: it produces a new project 'for geometry you did not author.' An agent can distinguish it from import_2d and other import/create siblings from the description alone.

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 clear operational guidance: pass `unit` when known, check `watertight` before building booleans, and import once then re-import with `repair` only if the mesh is not watertight. It lacks an explicit when-to-use-vs-alternative routing (e.g. vs import_2d or create_upload), which the schema mentions but the description does not.

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 (read-only, idempotent, non-destructive, closed-world). The description adds the behavioral facts that actually matter here: that long analyses are deferred rather than failing, that polling must continue until "done", the retry interval, and that `result` is byte-for-byte what the original tool would have returned.

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 sentences, front-loaded with the core action, then the lifecycle, then the result guarantee, then the exclusion. Every clause carries operational information; no filler or restatement of the title.

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?

No output schema exists, yet the description covers the return contract itself: the `status` field with its terminal value and the `result` field's equivalence to a direct call. Combined with the polling rules, an agent has everything needed to drive this tool to completion.

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?

Only one parameter at 100% schema coverage, so the schema baseline is 3. The description still adds meaning beyond it by explaining where `jobId` comes from (the deferred response of evaluate, print_check, measure, or check_interference) and that it stays usable across repeated polls.

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 (report/check) and resource (a deferred job handle) and explicitly names the sibling that handles the other deferred case: 'STEP jobs are polled with export_step, not here.' It also names the four tools that produce the handle, so an agent can immediately map the input to its source.

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 the full usage contract: when this tool is produced (slow analysis on a saved project that finishes in the background), the terminating condition (status is "done"), the polling cadence (wait `retryAfterMs` between polls), and the exclusion (STEP jobs go to export_step). Nothing about when or when-not to call it is left to inference.

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 this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine scope constraint (only folders you own or belong to), but says nothing about result size, pagination, or ordering. Adequate with gaps rather than rich.

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?

A single short fragment with the scoping constraint front-loaded and no wasted words. It is arguably too terse, since it reads as a noun phrase rather than a statement of what the call does, but nothing is padded.

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 zero-parameter tool with annotations covering safety, the main remaining gap is the return shape: there is no output schema, yet the description never says what a folder entry contains (e.g. name/ID), which an agent needs to chain into organize_project. The organize_project linkage partially compensates.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-parameter tool 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?

Names the resource (folders) and the scope (those you own or belong to), which separates it from list_projects and list_parts. The verb 'list' is only carried by the tool name and title, not the description body, so it is clear but not fully self-contained.

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?

Mentioning 'where organize_project can file a project' implies the follow-up call and why an agent would fetch folders, but it never states when to use this versus the other list_* tools or any prerequisite. Usage is inferable rather than explicit.

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 (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral value beyond that: parts are parametric and datasheet-dimensioned with authentic footprints/hole patterns, and it names the op used to consume a result. It stops short of describing return shape or pagination.

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 resource and its contents, then the insertion path and the usage nudge. Four short sentences, each earning its place, though the closing line leans slightly promotional.

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 read-only, parameterless-required browse tool with full schema coverage and full annotations, the description covers what it lists and why it matters. It could say a bit more about the returned item fields, but no output schema exists and the gaps are minor.

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 `search` and `category` are already documented. The description only implicitly touches parameter semantics by listing content categories, which hints at valid category values but adds nothing concrete. Baseline 3 applies when the schema does the heavy lifting.

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 resource (the built-in part library OwlCAD ships) and enumerates its contents (brackets, fasteners, spacers, reference bodies, mechanism pieces). This clearly separates it from the list_projects/list_folders siblings, which browse user content rather than the built-in library.

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 ('Reach for this before hand-modelling something that sounds standard') and routes to the follow-up action (insert via an edit_project `addPart` op). No explicit when-not/alternative exclusions, but the context is unambiguous.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the result ordering (most recently updated first) as behavioral context; pagination, cursor behavior, and page-size limits are left entirely to the schema, so the added value beyond structured data is modest.

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?

A single tight sentence that front-loads the resource and scope, then the ordering, then the routing hint. No filler, no restatement of the title.

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 read-only, parameterless-required list tool with a fully described schema and no output schema, the description covers what the tool returns (account projects, recency order) and why you'd call it. It stops short of describing return fields or pagination mechanics, but the schema's nextCursor references carry that load.

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 each parameter already documents itself thoroughly (cursor semantics, default/max limit, filtering behavior). The description adds no parameter meaning beyond that, 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 and resource ('The authenticated account's projects'), specifies the result ordering ('most recently updated first'), and explicitly positions itself relative to the sibling get_project by noting it is how you obtain an id. An agent can distinguish it from get_project and the other list_* siblings immediately.

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 trailing clause routes the agent to get_project, implying this is the discovery step before a by-id lookup. There is no explicit when-not guidance (e.g., versus list_folders or a name-search path), but the context is clear enough to select 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 cover safety (readOnly, idempotent, non-destructive), and the description adds value beyond them: results cannot be derived from a bounding box, and multi-body results flag operands that never touched. It does not describe performance cost or accuracy caveats, which is a minor gap.

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?

Two sentences, output list front-loaded, then the routing rationale and the body-count use case. Dense but every clause earns its place; slightly packed.

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 no output schema, the description compensates by enumerating the returned measurements and their intended interpretation. Combined with read-only annotations and a fully documented input schema, an agent has everything needed to call it correctly.

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 already documents every parameter in detail (scad/node tree, infill, shellMm, materialId, smoothness). The description adds no parameter-level meaning beyond that, so the baseline of 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 specific outputs (volume, surface area, centre of mass, connected-body count, filament/cost estimates) and explicitly differentiates from siblings: 'nothing else reports those.' An agent can route to measure without inspecting other schemas.

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 clear trigger questions ('how heavy / how much material / how much filament / how much will this cost') and an additional diagnostic use (checking a model is ONE body). It does not name a specific competing sibling tool (e.g. print_check, evaluate) or state when NOT to use it, so it stops short of full routing guidance.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds no behavioral context of its own — not the owner-only constraint, not whether the URL expires, not the 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?

One short sentence with no filler or repetition, and the key concept (a URL for the editor) is front-loaded. It is efficient, though the missing verb keeps it from being a model example.

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 one-parameter, read-only link-generating tool with no output schema and full schema coverage, the description conveys the return concept (a URL) but omits the owner-only restriction and any return-format detail. Adequate but with clear gaps.

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 projectId parameter, including its owner-only caveat, is documented in the schema. The description adds nothing beyond this, so the baseline of 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?

The description names a specific resource (a URL that opens a saved project in the OwlCAD editor) but is a noun fragment with no verb, so it is unclear whether the tool returns the link or performs the open. It does not differentiate itself from adjacent siblings like share_project or get_project.

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?

There is no statement of when to use this tool versus alternatives such as get_project or share_project, and no conditions or prerequisites are given. The only usage constraint (owner-only) lives in the schema, not the description.

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 destructiveHint=true and idempotentHint=true, so the safety bar is lower. The description still adds real context beyond them: filing causes the project to inherit the folder's members (a permission/access side effect) and explains how to reverse it by omitting folderId.

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 tight sentences, front-loaded with the action and scope, then the reversal path, then the discovery hint. No sentence is 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 two-parameter mutation tool with a destructive annotation and no output schema, the description covers the key facts: what changes, the membership inheritance side effect, and how to undo it. It does not mention permission requirements for filing into a shared folder, a minor gap.

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 parameters are already documented, including the omit/null semantics for folderId. The description reinforces rather than extends that meaning, so the baseline 3 is appropriate.

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 ("Move one of your projects into a folder, or out of one") and defines the domain concept of folders immediately. It clearly separates this from sibling tools like update_project or edit_project, which operate on project content rather than placement.

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 clear conditions: call with a folderId to file, call with none to unfile, and points to list_folders for discovering valid folders. It stops short of explicitly saying when to prefer this over a sibling such as share_project or update_project, so 4 rather than 5.

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, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's main contribution is the claim that this is a spatial check unavailable via tree reasoning. It adds real context but does not mention cost, runtime, or result shape, which is forgivable given the rich 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?

Three sentences, front-loaded with the core finding list, then usage timing, then trigger phrasing. No filler and no repetition of schema content.

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?

There is no output schema, so the description carries some return-value burden; it partially discharges this by naming the two reported findings. It stops short of describing result format (pass/fail vs numeric values, bed-fit verdict), leaving a small gap for a 7-parameter analysis tool.

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 every parameter (minWallMm, overhangDeg, printerId, smoothness, scad/nodes/projectId) is already documented in the schema. The description adds no syntax or default detail beyond it, 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 (Analyse) and resource (a model) and names the exact findings returned: overhang area beyond the safe angle and the thinnest wall. It also distinguishes itself from `evaluate` explicitly, so an agent can tell it apart from siblings like check_interference and evaluate.

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 explicit when-to-use ("before calling a part done"), an exclusion ("`evaluate` does not answer it"), and trigger keywords (supports, overhangs, thin walls, fits the bed, will it print). Nothing about routing to this tool is left to inference.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the result is delivered as a tool result, and owlcad://schema/primitives behaves differently with and without `keys` (index vs full ranges). It does not describe output format or size limits, keeping it below 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?

Two sentences, front-loaded with the core purpose before the parameter nuance. Every clause carries information an agent needs — the fallback rationale, the URI scope, and the keys behavior — with no 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 read-only reference reader with no output schema, the description covers purpose, selection condition, and the one non-obvious parameter behavior. It omits what the returned content looks like (structured vs prose) and any size considerations, a minor gap rather than a blocking one.

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 `keys` parameter already documents its primitives-only scope, so the baseline is 3. The description adds genuine meaning by contrasting the no-keys case (an index) with the with-keys case (full parameter ranges of named entries), which the schema does not spell out.

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 (reads an owlcad:// resource) and immediately clarifies the mechanism: it returns the resource as a tool result rather than via native MCP resource reads. This differentiates it from every sibling tool, none of which expose schema/reference content.

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 selection condition — use it when the client does not let you read MCP resources natively, and any owlcad:// URI referenced by other tools works here. It stops short of stating the inverse preference (use native resource reads when available), so it is clear context rather than full when/when-not routing.

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 declare this is a non-readonly, non-destructive, non-open-world, non-idempotent mutation. The description adds genuine context beyond that: the public-only constraint and the fact that a lineage link is retained. It omits duplicate-creation behavior implied by idempotentHint=false, keeping it just short of 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?

Three tight sentences, front-loaded with the core action, then the usage rationale, then the exclusion. No filler 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?

For a single-parameter tool with annotations covering the safety profile and no output schema, the description supplies everything needed to decide and call correctly: the action, the prerequisite (public), and the fallback for private projects.

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 parameter is already documented as 'The public project to fork.' The description only restates this as 'a PUBLIC project', adding no syntax, format, or ID conventions beyond the schema, so 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?

Names a specific verb+resource+outcome: fork a public project into a new owned project while preserving lineage. It is clearly distinguishable from siblings like get_project, update_project, and share_project, which neither create nor copy.

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 ('start from someone else's published model') and when not to ('only public projects can be remixed'), then routes the agent to the alternative workflow (read it and save the tree as a new project) for projects the user owns.

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, idempotentHint and destructiveHint=false, so safety is covered and the bar is lower. The description still adds real context: the output is a "flat-shaded diagnostic render, not a marketing shot," which sets expectation about visual fidelity, and it flags that this is the sole means of catching shape errors that validation misses.

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 sentences, front-loaded with the action and output format, then the use case, then a clarifying caveat about render style. Nothing is padded and every sentence carries distinct information.

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 an 8-parameter render tool with no output schema, the description covers purpose, when to invoke, and the nature of the returned image well enough to call it correctly. It does not describe the return payload shape (e.g. inline image vs URL) or multi-view result ordering, a minor gap given no output schema exists.

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 all 8 parameters thoroughly (views, size, scad/nodes/projectId exclusivity, azimuth/elevation pairing). The description only adds "one or more named views," which the schema's `views` field already conveys, so no meaningful uplift beyond the baseline.

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 ("Render the model to PNG images") plus the scope ("from one or more named views"), so the agent knows exactly what it produces. It also implicitly separates itself from the `evaluate` sibling by contrasting a tree that "evaluates cleanly" with one that "can still be the wrong shape."

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 use condition — check visual correctness after the tree evaluates — and frames itself as "the only way to notice" shape errors, which routes the agent here rather than to evaluate. It stops short of explicitly naming alternatives or stating when NOT to call it (e.g. for interference checks vs `check_interference`).

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 destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: the silent-degradation failure mode (a non-watertight mesh is dropped from a boolean with no error), and dryRun as a non-mutating preview. It does not state whether a repair is reversible or how partial failures are reported, leaving a modest gap.

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 sentences, front-loaded with the action and followed by the rationale and the dry-run escape hatch; nothing is redundant. The boolean-failure explanation is slightly long but it earns its place by justifying the tool's existence.

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 destructive, no-output-schema tool this covers purpose, trigger, risk, and safe preview well, and annotations carry the safety profile. The one omission is what a successful repair returns or reports, which the agent must infer.

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 projectId, nodeId, version and dryRun are all documented in the schema, including the subtle version-required-only-on-write rule. The description only restates dryRun's behavior, adding no syntax or format detail beyond the schema — baseline 3 is correct.

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 — finding non-watertight imported meshes and welding cracks, closing holes, fixing face directions — which is far more precise than the title alone. It is clearly distinguishable from siblings like edit_nodes, evaluate, or print_check because it names the exact defect class it targets.

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?

"Run this when a project contains an import and the geometry is not behaving" gives a clear triggering condition, and the dryRun sentence supplies a safe-preview path. It stops short of naming an alternative tool or an explicit when-not-to-use case, so it falls just short of the top band.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds that the write is scoped to the authenticated account and that the call returns an id, which is useful, but it says nothing about what happens on repeated calls despite idempotentHint=false, nor any quota/limits. Adds context over annotations without being rich.

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?

Two sentences, both earning their place: the first states the action and the return value up front, the second routes the agent to a better downstream deliverable. No restatement of the title or schema.

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 no output schema, the description usefully states the return value (the project id), and annotations cover the safety profile for a non-destructive write. What is missing is any note on repeat-call behaviour or whether the project name must be unique, but nothing blocks correct 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 description coverage is 100% and the schema documents name, scad and the full nodes tree in depth. The description contributes no parameter-level meaning beyond that, 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+resource ("Save a model as a project") and names the target scope ("on the authenticated account"), which separates it from read-side siblings like get_project, list_projects and from update_project. It does not explicitly contrast itself with remix_project or share_project, but the create-and-return-id framing 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 actionable routing advice: pair with open_in_editor, and the judgement that an editable link is usually a better deliverable than a bare mesh file. It stops short of an explicit when-not or a named alternative tool for the file-only case (e.g. export), so it is clear context rather than full when/when-not coverage.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is partly structured. The description adds genuinely new context beyond that: viewers get read-only access, anyone with the link can open it, and the revoke path (public=false) exists. It stops short of saying what revoking does to already-distributed links.

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-loads the core action and the returned link, then justifies the sibling routing. Four sentences, one of which ("This is usually the deliverable a person actually wants") is slightly chatty but still carries routing value.

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 no output schema, the description correctly promises the link as the return value, and it covers the mutation and its access implications for a 2-parameter tool. Remaining gap is only the lifecycle of links after revocation.

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 parameters are already documented, including the public default and the revoke semantics. The description reinforces the on/off framing but adds no format or constraint detail beyond the schema, which is the expected baseline here.

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+resource+effect: turning public link sharing on or off for a project and returning the link. It explicitly separates itself from the closest sibling by noting open_in_editor's link only works for the owning account, so an agent can route between the two 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?

Gives the selecting condition directly ("usually the deliverable a person actually wants") and names the alternative (open_in_editor) plus the reason it fails for handoff. It also adds a when-not caution: "only share what you mean to."

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 flag destructiveHint=true, and the description reinforces that cutting produces two parametric halves that remain editable and export as solids, plus the reassembly behavior of each joint. It never explicitly states that the original single body is consumed/replaced, which is the one destructive consequence left implicit.

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 layered with joint-selection rationale where it matters. Dense but every sentence carries decision-relevant content; slightly long for a single paragraph but no obvious 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 13-parameter destructive tool with no output schema, the description covers the key decisions (joint choice, position omission, parametric preservation) that the schema's terse field docs do not. Remaining gaps are minor: what happens to the source body and how the two resulting halves are referenced afterward.

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 bar is baseline 3, but the description genuinely enriches the joint enum — explaining that dowel sockets BOTH halves and prints the pin separately, pin/tenon grow the key from one half, and bolt is the only reversible option. It also ties position omission to cutting through the middle, adding meaning beyond the schema text.

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 ('Cut one body in a project into two halves at a plane') plus the outcome (a joint so they reassemble), and frames the exact use case ('my model is too big for my printer'). An agent can distinguish this from edit_nodes or repair_project without opening a 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 clear when-to-use context (model too big for the bed) and detailed selection guidance for the joint parameter, including tradeoffs like dowel costing a two-gram reprint vs. a whole half. It does not name a sibling alternative or state explicit exclusions, so it stops 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.

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: optimistic concurrency ("if the project has changed since, the update is refused rather than silently overwriting") and the preservation of id/link/history, which tells the agent this is a replace-in-place rather than a new artifact.

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 tight sentences, front-loaded with what is replaced and what is kept, followed by the concurrency rule and then the sibling routing. No filler or restated title.

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 destructive, non-idempotent mutation with annotations covering safety, the description covers replacement scope, preservation, concurrency and sibling routing. Minor gaps remain: it never says what the call returns (no output schema exists) and does not mention permission requirements.

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 all five parameters (including version's mismatch semantics) are already documented in the schema. The description restates the version/refusal rule in workflow terms but adds no syntax or format detail beyond it, and says nothing about name, scad or nodes. Baseline 3 applies when the schema carries the parameter burden.

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?

Specific verb+resource ("Replace the geometry of one of your existing projects") with the preservation guarantee spelled out (id, link, history). It also explicitly names the sibling it should not be confused with (save_project), so an agent can disambiguate 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?

Gives an explicit alternative and the condition that selects it: "Use this instead of save_project when iterating, so a person keeps one link." It also states the workflow prerequisite (pass the version you got from get_project) and the failure mode when the precondition is violated.

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