Server Quality Checklist

Tool Scores

• poietic_export_planeA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the export format and target plane, but does not mention whether an existing output file is overwritten, whether any workspace restrictions apply, what the tool returns on success or failure, or any side effects. This is a minimal behavioral disclosure for a file-writing operation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, well-structured sentence that front-loads the action and object, then clarifies the purpose. There is no redundant wording; every phrase adds useful meaning.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple export tool with three well-documented parameters and no output schema, the description covers the core purpose and format. However, it omits behavioral details like overwrite behavior and return values, and with no annotations to fill that gap, the description is not fully complete for an agent invoking it without extra context.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 three parameters. The description adds little beyond the schema: it restates the default 'current plane' concept and the intended use for 'later import', but does not provide deeper semantics such as path resolution rules or format constraints.

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

  Purpose5/5

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

  The description states a specific action ('Export') on a specific resource ('the current (or given) plane') with a precise output format ('a poietic design file'). It also distinguishes itself from siblings by noting the file is for 'later import', which contrasts with poietic_export_svg and poietic_import_plane.

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

  Usage Guidelines3/5

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

  The phrase 'for later import' implies the intended use case, and 'current (or given)' hints at flexibility. However, it does not explicitly name alternatives like poietic_export_svg for visual export or explain when not to use this tool, so usage guidance remains implied rather than explicit.

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

• poietic_redoA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the happy-path behavior and does not mention what happens when there is no undone transaction, whether redo can fail, or how the redo history is affected by subsequent edits.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is one concise front-loaded sentence with no filler. It efficiently states the action, target, and scope.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with a single optional parameter and no output schema, the basic action is clear. However, it lacks edge-case behavior and the relationship to undo history, so it is adequate but not fully complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, with the optional design parameter already documented as a path defaulting to the current design or POIETIC_DESIGN. The tool description adds no additional parameter-level meaning beyond what the schema already provides.

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

  Purpose5/5

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

  The description uses a specific verb ('Redo') and a specific resource ('the last undone edit transaction on the design'). It clearly distinguishes this from the sibling poietic_undo, which presumably performs the inverse operation.

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

  Usage Guidelines3/5

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

  The intended context is implied: redo is only meaningful after an edit has been undone. However, the description does not explicitly mention when to use it relative to poietic_undo, nor does it state any exclusions such as redo history being lost after new edits.

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

• poietic_write_dotA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description carries the full behavioral disclosure burden. It mentions the source-vs-file output mode, but does not disclose whether an existing output file is overwritten, what the response looks like when outputPath is provided, or any side effects of writing the file. For a write operation this is a notable gap.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded: it states the core purpose first, then the key behavioral variation. Every sentence earns its place with no filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is relatively simple and the schema covers all parameters, but with no annotations and no output schema, the description should clarify expected behavior more fully, especially the write path and any return value. It is minimally viable but not complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the parameters are already well documented. The description adds no additional parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description states a specific verb ('Write'), a clear resource ('the design graph'), and a concrete format ('Graphviz DOT file'). It also distinguishes itself by noting 'no pictogram dependency', which separates it from export-style siblings like poietic_export_svg.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool (when DOT output is desired without pictogram dependencies) and explains the outputPath omission behavior, but it never explicitly names alternatives or states when not to use it. Guidance is present but left largely to inference.

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

• poietic_arrangeA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It does disclose the core behavior: circle lays out nodes and align modes align given nodes, which clarifies what happens to selected objects. However, it does not state that this mutates the design, whether it persists, or whether it is reversible via poeitic_undo, which would be valuable for a layout-changing tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with the primary purpose, then a compact breakdown of modes. Every sentence earns its place and there is no filler or redundant restatement beyond what is needed.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given that there is no output schema and no annotations, the description is adequate but not fully self-contained: it explains modes and relies on the schema for parameters, but it omits the mutation/persistence nature, possible return value, and error or prerequisite conditions. This is sufficient for basic invocation but leaves side effects unclear.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the baseline is 3. The description adds some meaning by clarifying that circle can use all or given nodes and that align modes target given nodes, but it does not add format or default details beyond what the schema already provides.

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

  Purpose4/5

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

  States a clear, specific action: arrange nodes on the canvas, and enumerates the distinct layout modes (circle and align modes). It does not explicitly differentiate from sibling tools, so it loses the top point for sibling distinction, but the verb+resource pairing is unambiguous.

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

  Usage Guidelines4/5

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

  Gives clear context for when to use it: when nodes need to be laid out or aligned, with explicit conditions for circle vs align modes and whether refs are expected. It does not name alternative tools or state exclusions, so it is one step below explicit 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.

• poietic_export_svgA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It adds a useful dependency caveat: pictograms require a collection file and render as plain shapes without it. However, it does not mention other behavioral details such as whether existing output files are overwritten, what happens on failure, or what the tool returns after exporting.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences with no filler. The main purpose is stated first, and the important dependency caveat is placed second. Every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a straightforward export tool, the description covers the essential purpose and the main non-obvious dependency. The schema fully documents parameters, and the note about pictograms addresses the most likely source of confusing output. It could be more complete by discussing output behavior or alternatives, but the core context an agent needs to invoke correctly is present.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  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 six parameters. The description adds value beyond the schema by explaining that 'pictograms' requires a collection file from the Diagramming package and that omitting it degrades the visual output. This directly clarifies the pictogram parameter's semantics.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: exporting the current plane as an SVG diagram. The verb 'Export' plus the resource 'current plane' and format 'SVG' make the core action unambiguous. However, it does not explicitly differentiate this tool from sibling exporters like poietic_export_plane or poietic_write_dot, so it misses the top score.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: when an SVG export of the current plane is needed. However, it gives no explicit guidance about when not to use it or which sibling tool should be selected instead, such as poietic_export_plane for other export needs.

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

• poietic_new_designA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It explicitly discloses the main side effect of making the new design current, and 'new empty' signals that this is a non-destructive creation. It does not detail import copy semantics or failure modes, but the core behavioral profile is clear.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loaded with the primary action and side effect, and the optional import behavior is placed second. Every word earns its place with no redundancy or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with two simple parameters and no output schema, the description covers the essential aspects: creation, path, current-design side effect, and optional import. It is slightly incomplete in clarifying what import does to the source planes, but it is otherwise sufficient for an agent to invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema already documents both parameters well. The description adds contextual framing like 'new empty' and 'current design,' but it does not add new parameter-level constraints, formats, or semantics beyond what the schema provides.

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

  Purpose5/5

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

  The description opens with a specific imperative and object: 'Create a new empty Stock and Flow design at the given path and make it the current design.' This clearly states the action, resource, and observable side effect, and naturally distinguishes it from siblings like poietic_get_design and poietic_use_design, which operate on existing designs.

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

  Usage Guidelines3/5

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

  The description implies the primary use case — creating a new design and optionally seeding it with imported planes — but it never explicitly names alternatives or exclusions. It does not tell the agent when to prefer poietic_import_plane for importing into an existing design instead of using the import parameter here.

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

• poietic_import_planeA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It explains the identity modes and default behavior ('require'; object IDs must match), which is useful, but it does not describe conflict handling, whether the import overwrites existing content, or what the result of the operation is.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and front-loaded: the primary purpose is stated first, followed by a compact explanation of the identity modes. Every sentence adds useful information without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers the core purpose and identity semantics, but with no annotations and no output schema, it leaves out important operational details such as side effects, conflict behavior, error conditions, or what is returned after a successful import. It is adequate but not fully complete for a mutation-style tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already covers all parameters and the enum values. The description adds meaningful semantics by explaining what each identity mode means and clarifying that 'require' is the default, going beyond the schema's bare parameter definitions.

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

  Purpose5/5

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

  The description clearly states the action ('Import'), the resource ('a plane'), the source ('another poietic design file'), and the destination ('the current design'). This makes it easy to distinguish from sibling tools like export or validation tools.

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

  Usage Guidelines4/5

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

  The description provides a clear usage context: importing a plane from another file into the current design. It does not explicitly name alternatives or give exclusion criteria, but the intended use case is unambiguous.

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

• poietic_set_attributesA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden: it discloses version-dependent transaction behavior (single undo history entry on v0.8+ vs N entries on older builds) and states that the response indicates which mode was used. It does not cover overwrite/merge semantics or error behavior, but the disclosed transaction behavior is material and useful.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is four sentences, each carrying distinct information: the main operation, reference rules, version-dependent transaction behavior, and the edge caveat. There is no filler or redundant restatement, and the core purpose is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a three-parameter mutation tool with no annotations and no output schema, the description covers the reference rules, transaction versions, edge-specific constraints, and even notes the response mode. Return-value structure is not fully described, but the schema handles parameter context and the response-mode note partially covers what to expect.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful extra nuance beyond the schema, particularly the edge-specific rule that edges have no names and must be referenced by numeric ID.

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

  Purpose4/5

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

  The description opens with a specific action ('Set one or more attributes') and clearly scopes it to a node or edge, referenced by ID or unique name. It does not explicitly name sibling alternatives, but the verb+resource combination is clear enough to distinguish it from the other poietic_* tools.

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

  Usage Guidelines4/5

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

  The description gives clear operational context: attributes can be set on nodes or edges, IDs are preferred, unique names are accepted, and edges must use numeric IDs because they have no names. It does not discuss when to use this tool over specific sibling tools, but the guidance is sufficient for ordinary calls.

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

• poietic_add_nodeA
  4.2/5.0
  Behavior4/5

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

  Since no annotations are provided, the description carries the full behavioral disclosure burden. It reveals the return shape ({objectId, planeId}), warns that duplicate names resolve arbitrarily, and explains that formulas may be constants or expressions. It could mention failure modes or side effects in more detail, but the key behavioral caveat is well covered.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences deliver the core action, typical attributes with examples, return value, and a critical ID-preference warning with no filler. The most important information is front-loaded and every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers the return value even though there is no output schema, explains the most important attribute semantics, and gives a warning about duplicate names. It remains slightly incomplete in that it does not clarify how design selection interacts with node creation or describe potential validation errors, but for this tool's complexity the coverage is solid.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  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 meaningful semantics beyond the schema by naming typical attributes (name, formula, position) and clarifying that formula accepts constants or expressions. This helps an agent construct valid attribute objects that the generic schema alone would not convey.

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

  Purpose5/5

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

  The description opens with a specific action ('Create a new node') and concrete type examples (Stock, FlowRate, Auxiliary), making the tool's purpose unmistakable. It is clearly distinguished from sibling tools like poietic_connect or poietic_set_attributes, which perform different operations on nodes.

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

  Usage Guidelines3/5

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

  The description gives useful operational guidance—thread the returned objectId into later calls and prefer IDs over names—but it does not explicitly state when to choose this tool over alternatives such as poietic_set_attributes or poietic_auto_parameters. Usage context is implied rather than directly contrasted with siblings.

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

• poietic_auto_parametersA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that edges will be created and removed, mentions the consistency invariant, and says what is returned (created and removed edge IDs). It does not discuss reversibility or failure behavior, but it is substantially more transparent than most mutation tools.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences, each with a distinct job: state the operation, give the rationale and timing, and describe the return value. There is no filler or redundant restating of the tool name.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with one optional parameter, no output schema, and no annotations, the description covers purpose, behavior, timing, and return value. It could mention edge cases such as 'no changes needed' or error handling, but the core information an agent needs to select and invoke it is present.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The only parameter, 'design', is already fully documented in the input schema with 100% coverage. The description adds no parameter-level detail, but none is needed because the schema already explains the parameter adequately.

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

  Purpose5/5

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

  The description names a specific operation ('Automatically wire Parameter edges'), a specific resource type, and the two concrete behaviors: connect required parameter edges and disconnect unused ones. This clearly distinguishes it from generic sibling tools like poietic_connect or poietic_add_node.

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

  Usage Guidelines4/5

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

  It gives a clear trigger condition: run this after editing formulas and connections, and explains why it is necessary for model consistency. It does not explicitly name alternatives or state when not to use it, so it falls just short of full guidance.

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

• poietic_removeA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It discloses the critical destructive side effect—node removal also removes connected edges—and even mentions the CLI confirmation message. It does not discuss persistence, undoability, or not-found behavior, but covers the most important side effect.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences with the core operation first and the cascade warning immediately after. No filler or redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple two-parameter delete operation with no output schema, the description covers the intended scope and the key consequence. Minor omissions like error behavior and undoability do not prevent correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the schema already fully documents both parameters. The description repeats the ID-preferred/name distinction and adds no additional parameter semantics beyond this.

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

  Purpose5/5

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

  The description states a specific action ('Remove'), the resource ('object (node or edge)'), and the accepted reference forms (ID or unique name). It clearly distinguishes this from sibling tools like poietic_add_node or poietic_connect by focusing on deletion.

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

  Usage Guidelines4/5

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

  The description gives clear contextual guidance: prefer numeric ID, and warns that removing a node cascades to connected edges, which helps an agent decide when to use it. It does not explicitly name alternatives or exclusions, but no direct deletion sibling exists in this toolset.

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

• poietic_undoA
  4.2/5.0
  Behavior4/5

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

  There are no annotations, so the description carries the behavioral burden. It discloses the transaction model and the caveat about poietic_set_attributes with N attributes, which is valuable beyond what the schema or name provides. It could additionally state what happens when there is no edit to undo, but the core behavioral nuance is present.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is only two sentences, front-loads the primary action, and adds a concise clarifying note. Every sentence contributes useful information without unnecessary verbiage.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple tool with one optional parameter and no output schema, the description is adequately complete: it explains the action, the transaction unit, and the relevant edge case. It could mention no-op behavior if no prior edit exists, but this is not a critical gap for selecting and invoking the tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The single optional parameter 'design' is already fully described in the schema, and the description adds no extra parameter-level detail. With 100% schema description coverage, a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific action ('Undo the last edit transaction') and a clear resource ('the design'). It also clarifies undo granularity, distinguishing it from the other edit tools and from redo.

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

  Usage Guidelines4/5

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

  The description gives clear context on when to use the tool: after an edit, with the note that one undo corresponds to one edit tool call. It does not explicitly mention when not to use it or name poietic_redo as the inverse alternative, so it falls short of a 5.

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

• poietic_use_designA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It discloses the content-hash snapshot behavior and the conditional write-refusal state, which are important non-obvious behaviors. It stops short of stating whether this tool itself modifies the file, but the main statefulness is covered.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with the primary purpose, and no filler. The workspace restriction and stale-baseline consequence are conveyed efficiently.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a one-parameter state-setting tool with no output schema or annotations, the description covers its purpose, the main constraint, and a key failure mode. It could be slightly more explicit about side effects and which sibling tool performs the re-read, but overall it is adequate for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already fully documents the single 'design' parameter, so the baseline is 3. The description adds the workspace-origin detail, but this mostly restates the schema's 'inside the workspace' constraint rather than adding meaningful new parameter semantics.

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

  Purpose5/5

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

  States a specific action ('Set') and resource ('current design file'), and clarifies that it establishes session state for subsequent tools. This distinguishes it from siblings like poietic_get_design (read) and poietic_new_design (create).

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

  Usage Guidelines4/5

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

  Frames this as a prerequisite for subsequent tools, which tells the agent when to call it, and it gives a hard path constraint and a re-read instruction after external changes. It does not explicitly name alternative tools or state when not to use it, but the context is clear.

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

• poietic_metamodelA
  4.3/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses the output format (markdown), the optional parameter behavior, and the read-only exploration purpose via 'Describe' and 'schema-discovery path'. This is sufficient transparency for a query-like tool, though it does not explicitly state that no changes are made.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences, each earning its place: first states purpose and content, second explains optional parameter usage with examples, third explains why an agent would call this tool. No redundancy or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read-only tool with one optional parameter and no output schema, the description fully covers what the tool does, how to invoke it, what output to expect, and when to use it. Nothing critical is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 the single optional 'type' parameter. The description adds useful examples and restates the omit-for-all behavior, but does not add meaning beyond what the schema provides, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb 'Describe' with the Poietic metamodel as the resource, and details the content (object types, traits, attributes, edge types) and output format (markdown). It also clearly positions itself as the schema-discovery path, distinguishing it from the operational sibling tools.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: use it to inspect schema details, optionally for a single type or all types, and check attribute names before setting attributes. It does not explicitly name excluded alternatives, but the 'schema-discovery path' statement effectively separates it from sibling mutation and execution tools.

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

• poietic_validateA
  4.3/5.0
  Behavior4/5

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

  No annotations are present, so the description bears the full burden. It discloses the return shape and issue fields, and implies a non-mutating validation behavior. It does not explicitly state that the design is not modified, but 'validate' plus the return report makes this reasonably clear.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two dense, purposeful sentences cover the operation, the exact return structure, and the workflow position. No redundant wording or repetition of the tool name.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With a single optional parameter, no output schema, and no annotations, the description supplies everything an agent needs: what is validated, what the result looks like, and when to invoke it. This is sufficient for a low-complexity read-only validation tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The only parameter is fully documented in the schema with its path meaning and default resolution behavior. Schema coverage is 100%, so the description does not need to add parameter details; the baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool validates a design for errors, specifically formula errors and unknown parameters. This distinguishes it from sibling tools like poietic_run or poietic_get_design, which serve different purposes.

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

  Usage Guidelines4/5

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

  Explicitly tells the agent when to run this tool: after editing and before simulating. It does not explicitly mention alternatives or exclusions, but the timing guidance is clear and actionable.

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

• poietic_connectA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It discloses that edge attributes cannot be set at creation and should be set via poietic_set_attributes, and it states the return value, {edgeId}. It does not cover failure modes or idempotency, but for a straightforward creation operation it provides reasonable transparency.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is three concise sentences with no filler. The main action is front-loaded, followed by edge-type semantics, a caveat about attributes, and the return value. Every sentence contributes necessary information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with four parameters, no output schema, and no annotations, the description covers the core usage, edge-type semantics, attribute caveat, and return value. It is slightly light on edge-case behavior such as duplicate edges or invalid node references, but it is complete enough for correct invocation in most cases.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already covers all 100% of parameter descriptions, but the tool description adds important meaning beyond the schema: it explains that Flow direction follows the flow from FlowRate to Stock and that Parameter edges point from a value node to the node whose formula uses it. This is essential semantic information an agent cannot infer from the schema alone.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Create an edge between two nodes.' It also defines the two edge types with directional constraints (Flow between FlowRate and Stock, Parameter from value node to formula-using node), which clearly separates this from node-creation tools like poietic_add_node.

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

  Usage Guidelines4/5

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

  The description gives explicit context for valid edge types and their required endpoint roles, which tells the agent when this tool is appropriate. It also names poietic_set_attributes as the alternative for setting edge attributes. It does not explicitly contrast with sibling tools for adding nodes, but the edge-specific semantics make the intent clear.

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

• poietic_get_designA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and does so well: 'Read' signals a non-mutating operation, the full JSON shape is disclosed, and the warning that duplicate names 'resolve arbitrarily upstream' exposes a meaningful behavioral caveat. It also documents that this tool supersedes `list` and `show`.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and front-loaded: action, output shape, then useful caveats. Every sentence adds value, and the legacy replacement note plus ID guidance are included without bloat.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the simple optional parameter, the absence of an output schema, and no annotations, the description is remarkably complete: it defines the top-level response, node/edge shapes, default context, legacy behavior, and a key resolution warning. An agent has enough to call and interpret the result correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema already documents the single `design` parameter with 100% coverage, including its default behavior. The description adds little parameter-specific meaning beyond restating that it reads the 'current' design, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a clear verb and resource: 'Read the current Poietic design as normalized JSON.' It then names the exact output structure, which distinguishes it from export/format siblings like poietic_export_svg or poietic_export_plane, and explicitly says it 'Replaces `list` and `show`.'

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

  Usage Guidelines4/5

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

  The description clearly indicates this is for reading the current normalized design and calls out that it replaces `list` and `show`. It also gives practical guidance to prefer numeric IDs over names. It does not explicitly compare against many sibling tools, but the read-vs-export distinction is clear enough.

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

• poietic_runA
  4.7/5.0
  Behavior5/5

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

  With no annotations present, the description carries full responsibility for behavioral disclosure, and it does so thoroughly. It explains the return shape, side effects of outputPath, the nuanced effect of parameters on stocks versus other nodes, version-dependent behavior of allVariables, and that formula errors cause the run to fail.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but well-structured: it front-loads the core purpose and return value, then covers the key behavioral nuances in a logical order. Every sentence adds operational value, and the length is justified given the tool has 11 parameters and no annotations.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity (11 parameters, no output schema, no annotations), the description is remarkably complete. It covers the return format, parameter selection modes, override semantics, file persistence, version behavior, and failure conditions, leaving only minor details to the schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema already documents all 11 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics on top, especially for 'variables' (selection and default behavior), 'parameters' (stocks vs other nodes), and 'allVariables' (version-dependent inclusion), which goes beyond the schema descriptions.

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

  Purpose5/5

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

  The description names a specific verb ('Run') and a concrete resource ('Stock and Flow simulation'), and states exactly what it returns: a per-variable summary plus capped sample rows. This clearly distinguishes it from sibling tools like poietic_validate or poietic_get_design, which serve different stages of the workflow.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use each option: 'variables' for observing specific nodes, 'parameters' for overriding node values, 'outputPath' for saving the full CSV, and 'allVariables' for including internal variables. It also advises validating the design first, though it does not explicitly name poietic_validate as the alternative tool.

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