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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is partly covered. The description adds useful operational semantics (what each mode does, that offset moves along the target normal), but does not disclose that the move mutates the document, whether it needs an active assembly context, or how it interacts with existing constraints.

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?

Opens with a single front-loaded sentence stating the action, followed by a compact Args block. No filler, though the Google-style docstring formatting is slightly redundant with the structured 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?

Because an output schema exists, return values need not be explained, and annotations carry the safety profile. For a 9-parameter tool the description covers the parameters whose meaning is non-obvious (mode, offset, element/target element pairs), which is sufficient for 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 0%, so the description carries the burden. It clearly defines element/element_index and target_element/target_element_index, and fully specifies the mode enum values (touch=face-to-face with opposing normals, center=coincident centers, axis=cylindrical axes) plus the sign convention for offset. The only gap is that doc_name/obj_name/target_obj are not described, though their titles are largely self-explanatory.

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 an object so the chosen element aligns with an element of the target.' An agent can tell this is a positional alignment operation distinct from assemble/verify_assembly. However, it never names a sibling or the broader workflow it belongs to, so differentiation is implicit.

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 when-to-use guidance and no exclusions relative to neighbors like assemble, set_anchors, or verify_assembly. The description dives straight into argument semantics without telling the agent under what conditions this tool is the right choice.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral detail beyond that: partial-application semantics under stop_on_error and the subtle rule that nothing moves only if the FIRST mate fails. This transactional nuance is the kind of context annotations cannot 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?

Purpose is front-loaded, the alternative routing sentence follows immediately, and the args block is terse with no redundant restatement of the name or title. Every sentence earns its place.

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 the destructive/mutation role is well covered by annotations plus the transactional details. The only shortfall is the undocumented doc_name parameter, which matters for a required argument.

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 0%, so the description carries the full burden and does document three of four parameters, including units for tolerance ('mm'), the default value, and the constraint that mates must be non-empty. It omits any explanation of the required doc_name parameter, leaving one gap.

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 states a specific verb and mechanism ('Snap parts together by matching named anchors in one transaction') and explicitly contrasts itself with the sibling assembly_session for persistent joints. An agent can distinguish it from align_shapes, verify_assembly, and assembly_session 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?

It names the alternative (assembly_session) and the condition that selects it ('For persistent joints'), which is clear routing guidance. It also points to operation_help('assemble') for extended reference, though no other siblings (align_shapes, get_anchors) are addressed.

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 destructive=true and idempotent=false, but the description adds genuinely non-derivable behavior: parent moves propagate to children on re-solve, rollback(to_step) restores placements atomically, and state persists across calls. It stops short of covering failure modes or required permissions, so a 4 rather than 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 purpose and routing before the workflow and mate-ref syntax. Every line earns its place, though the inline mate-reference sentence is dense and the trailing operation_help pointer deflects detail that could have been stated.

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 stateful 11-parameter tool with 0% schema descriptions, the description covers the workflow spine and rollback semantics but leaves several parameter meanings and the exact operation-to-argument mapping unstated. An output schema exists, so return values need no explanation, and the operation_help reference partly offsets the gaps, but the definition is not fully self-sufficient.

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 0%, so the description must carry the parameter burden. It explains the operation vocabulary (start/add_component/mate/solve/verify/complete/rollback), part=ground, to_step, joint_type/trim, and the mate ref shape ({part} plus exactly one of face/anchor/point), but leaves a, b, name, doc_name, and gap_samples undefined. Partial compensation only.

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 ('Persistent-joint assembly on FreeCAD's Assembly workbench') and explicitly positions it against the sibling 'assemble' ('prefer it over the one-shot assemble when joints must survive later moves'). An agent can distinguish it from assemble 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?

Names the alternative explicitly and the condition that selects it (joints must survive later moves), and supplies the ordered workflow (start, add_component, mate, solve, verify, complete). Routing decision is fully determined without 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: 'Committed mutations are rollback-able session steps' and that stop_on_error halts a batch at the first failure. It still doesn't say what a mutation can destroy or what permissions are needed.

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 purpose, then the obj_name/obj_properties rule, then the rollback note, then an Args list. Nearly every line earns its place; the Args block mildly restates what the opening sentences imply but stays compact.

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 described, and annotations cover the safety profile. For a 23-operation mutation tool the definition supplies the key invocation rules (object semantics, batch error handling, rollback-ability) and delegates operation details to operation_help; only doc_name 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?

With schema description coverage at 0% and 8 parameters, the description must compensate, and it largely does: it explains obj_name (base object, or new object for loft/sketch/variables/datum_plane/hull), obj_properties (where params go), obj_type, ops, stop_on_error, and description. Only doc_name and operation lack prose, and operation is a self-evident enum.

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 concrete verb and resource ('Run one CAD modeling operation') and adds a role label ('the unified mutation entry point') that separates it from the read/inspect siblings like get_objects, get_view and measure_geometry. It stops short of explicitly contrasting with execute_code or session, so sibling differentiation is only partial.

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?

Usage is implied rather than stated: it routes the agent to operation_help('<operation>') for operation-specific guidance and clarifies which ops treat obj_name as new vs. base. There is no explicit when-to-use-this-vs-execute_code/session guidance or when-not 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the computed outputs, which the output schema already carries; it discloses nothing further about behavior such as cost, limits, or failure modes.

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, purpose front-loaded, with the return payload called out explicitly. No filler or 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?

The output schema exists and the description redundantly restates the return keys, so return values are covered. However, for a 3-parameter tool with zero schema documentation, the description leaves the caller guessing about argument formats, which is a real completeness 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 description coverage is 0% for all three parameters. The phrase 'two objects' loosely maps to obj_a/obj_b, but nothing explains whether these are names, IDs, or paths, and doc_name is never mentioned. The description does not compensate for the documentation gap.

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 gives a specific verb+resource ('Check two objects for interference') and enumerates the exact quantities computed (distance, common volume), so the agent knows precisely what it gets. It does not name or contrast itself against the closest sibling, measure_geometry, so it falls short of a 5.

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?

'Use it to verify clearance or detect collisions' states the intent that selects this tool, giving clear usage context. It offers no exclusions or named alternatives (e.g., when plain measurement suffices), so it is a solid 4 rather than 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 non-read-only, non-idempotent, open-world behavior, so the bar is lower. The description adds genuinely useful non-obvious behavior: FreeCAD may sanitize or deduplicate the requested name and the caller should read the actual name from the result. It does not say what happens on name collisions or failures, but the sanitization warning is a meaningful disclosure.

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?

Extremely short, front-loaded with the purpose, and every sentence adds value. The Args block is slightly boilerplate for one parameter but carries real semantic 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?

An output schema exists, so return values need not be enumerated, though the description usefully points the agent to read the actual name from the result. What's missing is lightweight usage context (session prerequisites, behavior when the document already exists), which is minor for a one-parameter creation 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 coverage is 0% for the single 'name' parameter, so the description must compensate. It does so by explaining that the name is not guaranteed to be preserved (sanitized/deduplicated) and that the real value must be read from the output, which the bare string schema does not convey.

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 ('Create a new FreeCAD document'), which is unambiguous and distinguishable from list_documents or session siblings. It does not explicitly contrast itself with sibling tools, but the action is clear enough for selection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no prerequisites (e.g., an open session), and does not mention alternatives such as list_documents. Usage is only implied by the verb 'Create'.

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 mutation (readOnlyHint=false), idempotent=false, and openWorldHint=true. The description adds genuinely useful behavioral context: the tool runs even when FreeCAD is unreachable, and 'dismiss' closes the blocking modal via Cancel with 'nothing confirmed'. That side-effect disclosure goes 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-loads the core purpose in the first clause, then what it probes, then per-parameter notes. The Args block and operation_help reference are well-structured; slight redundancy in phrasing but nothing wasteful.

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, and the description covers both parameters plus the failure-state usage context. For a two-param diagnostic tool this is nearly complete; only explicit alternative routing 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 0%, so the description carries the full burden, and it does: host is explained as defaulting to the server's --host, and dismiss is explained as closing the modal dialog ('Cancel, nothing confirmed'). Both parameters gain meaning not present in 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+outcome ('Find out why CADPilot cannot reach FreeCAD') and enumerates exactly what it probes (RPC port, process, addon install, its logs). This is unambiguous and separable from siblings like inspect_freecad or get_addon_log, which address narrower concerns.

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?

Clearly frames the context: use it to diagnose unreachable FreeCAD, and it 'works while FreeCAD is down', which tells the agent it is safe to run in the failure state. It stops short of naming an explicit alternative or when-not-to-use condition, so it's clear but not fully 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 already declare destructive/non-idempotent/open-world, and the description adds material context beyond them: the run is transactional, a mutating snippet commits as one undoable step, a read-only run is not journaled, and print() output is captured. Undo grouping and journaling behavior are exactly the traits an agent cannot infer from the 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?

Front-loaded purpose sentence, then one transactional sentence, then a compact Args block — every line carries information and nothing is repeated from the schema or annotations.

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 thread, transaction, doc binding and both parameters are covered. The remaining gap is the blocking/timeout profile of running arbitrary code in the GUI thread versus the async sibling, which an agent choosing between the two would want.

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 0%, so the description carries the full burden and does: the '#' comment convention that becomes the step row label is a non-obvious semantic, and doc_name's binding of transaction, step journal and ActiveDocument plus its default fallback chain is spelled out. This adds real meaning the bare schema lacks.

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 precise verb+resource ('Run Python in FreeCAD's GUI thread') and immediately scopes it with the pre-imported modules and the fact that print() output is returned. The GUI-thread qualifier cleanly distinguishes it from the sibling execute_code_async.

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 GUI-thread framing implicitly tells the agent this is the synchronous/in-thread path versus execute_code_async, and the transactional paragraph clarifies mutating vs read-only intent. It never explicitly says when to prefer the async sibling or warns that long code blocks the GUI, so guidance is clear 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 destructive/openWorld/non-idempotent, and the description adds non-obvious behavior: async threading, output only via task_print, print() silently not captured, and a hard GUI prohibition list. It does not discuss concurrent execution or failure states of the task, but the added runtime semantics are substantial.

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 and return value, then constraints ranked by importance (GUI prohibition, output channel), with the arg note last. Every sentence carries actionable information and none is redundant with the 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?

An output schema exists so return values need no explanation, and the description covers execution mode, constraints, result retrieval, and the output channel. What remains thin is failure/error behavior and how a returned task_id should be treated if the thread dies, but the essentials are present.

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 0% (the lone 'code' property has only a title), so the description carries the burden and does add meaning: the code must be 'Background-safe Python' with no GUI, document, recompute, or save calls, and must use task_print for output. That is meaningful constraint beyond the bare parameter name, though no format/length expectations are given.

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 with the execution model named: 'Run Python on a background thread and return a task_id'. It also draws a boundary against the sibling execute_code, so an agent can distinguish the two without opening 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?

Explicit when-to-use routing: use execute_code when GUI/document interaction is needed, and poll this task's result with get_task_result. Both the alternative and the follow-up condition are named, leaving nothing 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 safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral facts beyond them: the log is a ring buffer (bounded retention) and records are ordered newest-last. It does not say what happens when the buffer wraps or whether results can be truncated, which keeps it from 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 purpose, followed by a tight Args block where each entry is one line and earns its place. The trailing 'Reference: operation_help(...)' line is a low-value pointer that could be trimmed. Overall efficient and well ordered.

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 formatting need not be explained. Combined with the annotations and the per-argument semantics, an agent has enough to call it correctly. Minor gaps remain around buffer wrap behavior and the limit ceiling.

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 0% – the schema only has titles and defaults – so the description must carry the load, and it largely does: it enumerates the level values (DEBUG/INFO/WARNING/ERROR), specifies grep as a substring filter over 'message and detail', defines since_seq as a sequence cursor, and restates the limit default. The limit maximum of 1000 and the precise semantics of level vs. default INFO are not spelled out, so not a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read the addon's ring-buffer debug log') plus the ordering guarantee ('newest last'). It also frames the operational situation ('while FreeCAD is wedged or a call misbehaves'), which makes the intent unambiguous. It does not explicitly contrast itself with the sibling 'diagnose' or 'operation_help', so it stops short of a 5.

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 triggering context: use it when FreeCAD is wedged or a call misbehaves. That is genuine when-to-use guidance rather than implied usage. It names no exclusions or alternative tools for overlapping diagnostic needs, so no 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 (readOnly, idempotent, non-destructive), and the description goes well beyond them: it enumerates the auto-derived anchor families, explains the merge/precedence rule with set_anchors, and specifies the return shape including the source field. That is exactly the extra behavioral context annotations cannot carry.

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 and coordinate scope, then merge semantics, then the imperative usage note, then the return shape. Every sentence earns its place; the parenthetical anchor list is dense but genuinely useful.

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 tool, the description covers purpose, merge behavior, usage timing, and return structure; even though an output schema exists, restating the shape is harmless and helps the agent plan mates. 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?

Two required parameters with 0% schema description coverage, so the description carries the burden; it says 'an object's' anchors but never explains doc_name vs obj_name, their formats, or whether the object must exist. The implied mapping is inferable but not spelled 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 (List) plus resource (assembly anchors) and a critical qualifier (GLOBAL coordinates), which immediately separates it from get_topology, measure_geometry and get_positioning_info. The agent knows exactly what it gets back.

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 directive: 'Call it before placing parts and plan mates from the returned numbers; never guess coordinates.' This is clear when-to-use guidance, and the 'explicit wins' merge note implicitly positions it relative to set_anchors. No explicit when-not or named alternative, 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the tool returns either a list or a single object depending on obj_name, and the list is paginated via limit/offset.

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 purpose in the first sentence, then uses an Args block for parameter notes. Every line is relevant; the formatting is slightly repetitive but not wasteful.

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 annotations carry the safety profile. Combined with the mode and pagination guidance, the definition is nearly complete, missing only documentation of the required doc_name parameter.

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 0%, so the description must carry parameter meaning. It explains obj_name well and gives semantics for limit/offset ('page size and start index'), but the required doc_name parameter is never mentioned in the description, leaving a notable gap.

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 ('List a document's objects, or read one object's full properties') and clearly captures the dual-mode behavior. It doesn't explicitly reference siblings like list_documents, but the resource scope (objects within a document) 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 explicit conditional guidance for the dual mode: omit obj_name to list, pass a name to read. This is clear context for selecting behavior. It stops short of naming alternative tools or exclusions, keeping it at a 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: results are in global coordinates and 'the Placement is already applied', which tells the agent how to interpret returned values without extra transformation.

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 output fields and the sibling preference are front-loaded in the first two sentences before the Args block, and there is little waste. The field list (center, normal, axis, radius, endpoints) is slightly dense but relevant.

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 formatting need not be re-explained, and annotations cover the safety profile. The main residual gap is the undocumented doc_name/obj_name parameters, but overall an agent has enough to invoke this 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 description coverage is 0%, so the description must carry the parameter burden. It explains element (face/edge/vertex) and element_index (0-based, indices obtainable from get_topology) well, but doc_name and obj_name are left entirely undocumented in both schema and description.

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 states a specific resource (one face, edge or vertex), the coordinate frame (global), and the exact payload returned (center, normal, axis, radius, endpoints). It explicitly distinguishes itself from the sibling get_topology, so an agent can select it 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?

It names the alternative explicitly ('Prefer it over get_topology for precise positioning before alignment or assembly') and gives the condition that selects the alternative ('call get_topology to find the indices'). The when-to-use and sibling routing are both explicit rather than inferred.

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, destructiveHint=false and openWorldHint, so safety and repeatability are covered by structured data. The description usefully adds the status vocabulary (running | done | error) and the fact that output/traceback are captured, but says nothing about polling intervals, output truncation, or whether the task record expires once read.

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 purpose sentence is front-loaded in one line, and the Args/Returns block is compact and scannable. The Returns line partially duplicates the existing output schema, a small redundancy, but nothing bloats the definition.

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 polling tool it covers the essentials: what is fetched, the required argument's origin, and the status states. Since an output schema exists, the return explanation is a bonus rather than a requirement, and only the polling mechanics remain unspecified.

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 0% and the schema only supplies a title and minLength, so the description carries the burden. It does so by defining task_id as the ID returned by execute_code_async, which tells the agent where the value must come from — meaningful added semantics 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 (Poll) plus the resource (status and captured output of one execute_code_async task), and explicitly ties itself to the sibling that produces the input. An agent can distinguish it from execute_code_async and execute_code 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?

"Poll" plus "Task ID returned by execute_code_async" makes the trigger condition clear: call this after starting an async execution, repeatedly until completion. There are no explicit exclusions or guidance on polling cadence versus other result-retrieval paths, 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds real behavioral value on top with the 'largest first' sort order and the fact that pagination exists. It does not discuss error behavior or what happens when an object has no topology, which keeps 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?

Front-loaded with the purpose and ordering before the Args/Returns blocks, and every line earns its place. The Args block partly restates schema defaults/ranges, which is mild redundancy but aids readability rather than bloating the definition.

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, paginated listing tool, the definition covers ordering, pagination controls, the shape of the result and the downstream purpose of the returned names. The only gaps are edge-case behavior (invalid element, empty topology) and any explanation of doc_name/obj_name scoping.

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 0%, so the description must carry the load, and it documents the three non-obvious parameters: element (faces/edges/vertices), limit (1–200, default 50) and offset (skip count). doc_name and obj_name are left undocumented, but their meaning is self-evident from the names and required-parameter list.

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 ('List an object's topology') plus the exact sub-entities covered (faces by area, edges by length, vertices by distance) and their ordering. This clearly separates it from siblings like get_objects (whole objects) and measure_geometry (measurements), so an agent can pick 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?

Gives a concrete use context: 'for selection', with the returned names feeding fillet, boolean and sketch-on-face operations. That tells the agent when the tool is appropriate, but it offers no explicit when-not or named alternative for topology-like queries, 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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the tool is context-costly, returns a saved PNG path, and caps the long edge at 384 px when width/height are omitted. It stops short of describing session/GUI prerequisites for the capture.

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 the cost caveat, then a compact Args block; each sentence carries information. The Args list slightly overlaps the schema, but with 0% schema coverage that redundancy is doing necessary work.

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-value detail is not required, and the safety/behavioral burden is largely carried by annotations. Combined with full parameter documentation and the cost warning, an agent has what it needs to call it correctly; only GUI/session preconditions remain unstated.

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 0%, so the description carries the full burden, and it documents all five parameters: view_name (one of nine), width/height (pixel size with a context-saving rationale), focus_object (fit behavior), and doc_name (foreground-tab hazard). The only gap is that enum membership and min/max bounds live in the schema rather than being restated.

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 ('Capture one document's view') and names the concrete return value ('the saved PNG's path'). It also differentiates from siblings by pointing to get_objects and measure_geometry for numeric needs, so an agent can distinguish it without opening 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?

Explicitly says when to use it ('reserve it for visual checks') and when not to ('prefer get_objects or measure_geometry for numbers'), naming the alternatives. The doc_name note also warns of a real hazard (another agent may have switched the foreground tab).

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, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavioral context: it explains that the two call modes (doc_name+obj_name vs dotted_name) return different kinds of information. It does not cover failure modes (invalid names, missing objects), which keeps 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 short sentences, zero filler, and the routing constraint is front-loaded before the parameter explanation. Each clause earns its place.

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 and rich annotations, the description need not explain return values, and it covers purpose, routing, and per-parameter behavior adequately. The only missing piece is behavior when all three optional parameters are omitted.

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 0%, so the description must carry the burden — and it does, mapping doc_name+obj_name to object introspection (TypeId, settable properties, methods, docstring) and dotted_name to a docstring/member list, with a concrete example ('Part.makeLoft'). It does not state what happens if no arguments are supplied, leaving one gap.

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 gives a specific verb and resource ('Inspect the live FreeCAD Python API') and immediately positions the tool against a named sibling ('recall_patterns'), so an agent can tell it apart from get_objects, operation_help, or diagnose without opening 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?

It states an explicit selection condition — 'the last resort when your own knowledge and recall_patterns are insufficient' — naming both the prerequisite (exhausted knowledge) and the alternative (recall_patterns). This is the kind of routing guidance that prevents premature introspection calls.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds only the 'open documents' scope qualifier, which is useful context but not rich behavioral disclosure.

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?

Very short and front-loaded, with the core action first and the args note second. The 'Args:' block is slightly schema-like boilerplate but costs little.

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 operation is simple. Still, the description gives no guidance on result ordering, whether pagination is needed for large sessions, or how this differs from sibling listing tools.

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 0%, so the description must carry parameter meaning; it labels limit/offset as 'Page size and start index', which is a real clarification. However it omits the defaults (50/0) and the max bounds (500, 10,000,000) that constrain valid calls.

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: listing open FreeCAD documents. The scope word 'open' usefully distinguishes it from siblings like get_objects, though it doesn't explicitly name an alternative tool for listing documents on disk.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_objects or inspect_freecad. The agent must infer from the name alone when this tool is the right entry point.

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 establish this as a safe, read-only, idempotent operation, so the description doesn't need to restate safety. It adds genuine behavioral context instead: numeric precision (6 significant digits) and the accuracy caveat that bbox is exact for planar shapes but ~0.1 mm off on curved ones — information an agent needs to judge whether results meet a tolerance.

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 and the precondition in the first sentence, followed by a compact return block. The precision/bbox caveat is dense but earns its place since it affects interpretation of results.

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 the return-field listing is optional bonus rather than required, and the precision caveat is a useful extra. The precondition is stated and the tool is a simple two-parameter read, but the total silence on what doc_name/obj_name must contain leaves a small but real 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 description coverage is 0% and both parameters (doc_name, obj_name) carry no titles beyond the field name, so the description bears the full burden. It only obliquely hints at obj_name via 'the object must have one' and says nothing about doc_name or how the pair identifies the target, leaving the parameters effectively undocumented.

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 (measure an object's Shape) and the goal (verify a design target numerically), which is enough to distinguish it from siblings like check_interference or get_topology. It never names those alternatives, so differentiation relies on the agent's own inference.

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 parenthetical precondition 'the object must have one' tells the agent a Shape is required before calling, which is real guidance. Beyond that, there is no when-to-use vs. alternatives guidance (e.g. vs. get_topology or inspect_freecad), so usage is only implied by the stated goal.

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 covered. The description adds the no-argument fallback behavior (returns a topic list), which is useful but modest added 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?

Two sentences with zero waste. The core purpose is front-loaded and the invocation details follow immediately, with 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?

For a simple single-parameter help tool with an output schema, the description supplies what an agent needs: what it returns and how to invoke it. Return format need not be explained since an 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 0%, so the description must carry the parameter's meaning, and it does: it explains the argument is an operation name, gives a concrete example ("sketch"), and clarifies that omitting it yields the topic list. This compensates well for the undocumented single optional parameter.

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 clearly that it provides a full parameter reference for a cad() operation or other topic, a specific verb+resource (reference retrieval). It implies its relationship to the cad sibling but does not explicitly name or contrast with any alternative tool.

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 invocation guidance: pass an operation name like "sketch", or call with no argument to get the topic list. This covers both the argument and no-argument paths, though it names no alternative tools for discovery.

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 readOnly, idempotent, non-openWorld and non-destructive, so the safety profile is covered. The description's only added behavioral content is the return shape ('JSON list with code/steps'), which largely duplicates the existing output schema, and it says nothing about memory scope or staleness.

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 action and its timing rule, then cleanly separates Args and Returns. No filler sentences; each line conveys 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?

Covers purpose, usage trigger, both parameters, and the return nature for a simple two-parameter read tool. The return description is partly redundant given the output schema, but 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 0%, so the description must carry the load, and it does: query is defined as task keywords with a concrete example, and limit is explained as max results with its default. Only the upper bound (50) and format constraints are left to 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: searching the pattern memory for workflows/code similar to the task. It is clearly distinguishable from save_pattern by intent (recall vs store), though it never names that sibling explicitly.

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 trigger: 'do this before trial and error when your knowledge may not cover it.' That is strong when-to-use guidance, but it offers no exclusions or named alternatives (e.g. save_pattern, operation_help) for 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 already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the safety story is covered. The description adds that the pattern is stored 'for later recall' and returns a pattern_id, but says nothing about persistence scope (session vs. global), duplicate handling despite non-idempotency, or storage limits.

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 one-line purpose followed by a tight Args block and a single Returns line; every sentence earns its place. The Args formatting is slightly boilerplate-heavy for four short fields, but nothing is 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?

An output schema exists, so the brief Returns line is a bonus rather than a necessity, and all four parameters plus the use trigger are covered. The remaining gap is behavioral: an agent cannot tell whether saved patterns persist across sessions or whether repeated saves create duplicates.

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 0%, so the description carries the burden and mostly does: it explains all four parameters, including an example for name, the intent of description, that code is an optional Python snippet, and that tags drive retrieval. It does not clarify the tags format or length constraints, but it is well above the low-coverage 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 ('Store a reusable modeling pattern for later recall') and even gives an example name, so the operation is unmistakable. It implies its counterpart (recall_patterns) via 'for later recall' but never names it, so sibling differentiation is only implicit.

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?

'call this after a non-trivial approach worked' gives a concrete trigger condition for use. It stops short of stating when not to save (trivial cases, duplicates) or explicitly pointing at recall_patterns as the retrieval counterpart.

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, openWorldHint=true, idempotentHint=false and readOnlyHint=false. The description adds real value by explaining the transaction/rollback/redo model, which is not derivable from annotations. However, it does not distinguish which of the ten actions are safe reads (status, get_steps, list) from destructive ones (rollback discards steps, complete writes a file), which is exactly the context an agent needs given the blanket destructiveHint.

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 compact blocks: a one-line conceptual framing followed by a dense action/parameter map. Front-loaded and free of filler, though the pipe-delimited action list is terse enough that some semantic detail is sacrificed for brevity.

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 needn't be described. For a 10-action, 16-parameter dispatcher the description covers the call shape well but leaves per-action behavior undefined (what to_step=null means, whether pause persists state, what 'force' overrides), relying on operation_help to fill the 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 description coverage is 0% — parameters carry only title/default metadata — so the description must compensate, and it does: it maps nearly every parameter to its action (start: doc_name/create_document, rollback: to_step/force, redo: n, add_note: note/note_type, resume: session_id, complete: save/save_path/description/tags, get_steps: limit/offset). Only 'name' and the optionality/format semantics of to_step are unaddressed.

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 opening sentence states a specific resource and its defining behavior: a modeling session bound to a document, with cad() mutations becoming transaction-backed, rollback-able steps. It distinguishes itself from the sibling assembly_session by being the modeling/CAD-edit session. It's clear, though the multi-action dispatcher nature means no single verb captures the tool.

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 action list implies what each mode does (start, rollback, redo, complete, etc.) but never says when to reach for this tool versus alternatives like step_plan, step_control, or assembly_session. There are no exclusions or prerequisites, and it deflects detail to operation_help("session").

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 — anchors persist with the document, follow its Placement, and the write is recorded as a modeling-session step (i.e., an undoable history artifact). The replace semantics clarify what actually gets destroyed.

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 one-line summary followed by a tight Args block; each arg line carries real information (nullable dir, conversion behavior). The middle sentence about persistence and session steps could be trimmed slightly but earns its place as the main behavioral disclosure.

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 5-parameter mutation tool with nested input, an output schema present, and full annotation coverage, the description supplies the mutation semantics (merge vs replace), the coordinate interpretation, and the durability/undo behavior. Remaining gaps are minor: no mention of error cases or what happens on a name collision beyond replace.

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 0%, so the description carries the load, and it does: anchors is documented as a name→{pos, dir|null} nested structure, replace as wipe-vs-merge, and coord_frame as local-as-given vs global-converted. Only doc_name and obj_name are left undocumented, though their purpose is self-evident from the names.

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 ("Define named anchors on an object") and immediately characterizes the effect (persistence, attachment to Placement). It is clearly distinguishable from the sibling get_anchors by the write verb, though it never names that sibling or other neighbors explicitly.

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?

Usage is implied rather than stated: the merge-vs-replace note tells the agent which mode to pick, and the coord_frame note says when to use global ("for global source coordinates"). There is no explicit when-to-use-this-vs-alternatives guidance or prerequisite statement.

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, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral detail beyond that: reset requires confirm=true. It does not disclose which actions mutate or destroy journal state, nor the effect of force or index.

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 sentence, compact pipe-delimited action list, and a pointer to operation_help for detail. No filler, though the bare action list is dense rather than informative.

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. But for a destructive, six-parameter tool with zero schema descriptions, the description leaves the interaction between action and its companion arguments (index, params, force) entirely 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 0%, so the description must carry the load. It does supply the critical action vocabulary (which the schema leaves as an undescribed plain string) and ties confirm=true to reset, but index, force, params, and doc_name are given no meaning at all.

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 set of verbs (review, run, undo) over a concrete resource (a document's step journal), and the action enumeration makes the scope unmistakable. It does not explicitly contrast itself with the sibling step_plan, which is the main reason it isn't a 5.

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?

Listing the 14 valid actions implies what the tool can do, and one precondition is given (reset needs confirm=true). However it never says when to pick run_to vs rollback_to vs reexecute, nor when to use this tool rather than step_plan. Usage must be inferred from the action names.

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 establish the mutation/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds meaningful context beyond them — that nothing is executed on submit and that the plan is released manually via the panel or step_control. It omits whether re-submission or cancellation is possible.

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, front-loaded lines with no filler; the core behavior leads and the mechanical detail follows. The trailing reference line is functional but slightly boilerplate.

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 described. However, for a non-read-only plan-submission tool with three parameters at 0% schema coverage, the description leaves doc_name semantics and the fate/lifecycle of a submitted plan 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 0%, so the description carries the burden. It clarifies that each element of 'steps' is a cad() argument dict, which is valuable, but says nothing about doc_name or the optional description field.

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 (submit) plus resource (modeling plan to the document's step journal) and immediately adds the key scope qualifier 'without executing it'. This separates it from cad/execute_code, though it does not name those siblings directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining what happens after submission ('waits for release in the CADPilot Steps panel or via step_control'), but never states when to choose step_plan over cad or when not to use it. Usage is inferable, not 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, openWorld), so repeating 'read-only' earns nothing. The description adds genuinely new behavioral detail: hidden objects are skipped, thresholds default to 1.0, and measurements are in mm/mm3 — facts an agent cannot get 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 purpose in the first sentence, followed by the hidden-object caveat, an Args block, and a Returns line. Every element is short and earns its place, though the Returns line is somewhat redundant given the output 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 read-only audit tool with four parameters and an existing output schema, the description covers purpose, skip behavior, units, defaults, and per-parameter meaning. Nothing an agent needs 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 0%, so the description must carry the burden, and it does for three of four parameters: checks is the optional anchor-pair distance list, float_threshold is the gap in mm above which a part floats (default 1.0), and interference_min_volume is the smallest reportable common volume in mm3. Only doc_name is left unexplained, and it is self-evident.

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 ('Audit a document's spatial health') and enumerates the three checks it performs: floating parts, interferences, and anchor-pair distances. This implicitly separates it from narrower siblings like check_interference and measure_geometry, though no sibling is named explicitly.

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?

Usage is implied by the audit framing and reinforced by 'Trust these numbers over a screenshot,' which tells the agent this is the authoritative verification step. However, there is no explicit when-not or alternative routing against overlapping siblings such as check_interference or measure_geometry.

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