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

With no annotations, the description fully bears the transparency burden. It states that it returns a canvas URL and optionally runs a cost simulation. However, it does not disclose details about validation, potential destructive actions, auth requirements, or rate limits. This is adequate but not thorough.

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

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

Three sentences: the first states the core action, the second adds return value, the third adds optional cost simulation and usage guidance. No wasted words, and the most important information is front-loaded.

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

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

Given the moderate complexity (5 parameters, nested objects, 1 required) and no output schema, the description is mostly complete. It explains the return (canvas URL) and optional cost simulation. It could mention that the prompt must be a system description, but schema already covers that. Slight gap in explaining validation.

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

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

Schema coverage is 100% and all parameters have descriptions. The description adds 'Optionally runs a cost simulation' which reinforces the simulate parameter but doesn't add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it turns a natural-language system description into a validated cloud architecture and draws it on the canvas, specifying both the verb (build/draw) and the resource (architecture on canvas). It distinguishes from siblings like pinpole_create_architecture which may not draw, and pinpole_draw_on_canvas which may not create.

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 says 'Use this when the user wants to design or visualize a system/architecture.' This provides clear context. While it does not explicitly exclude other tools or list alternatives, the sibling context implies differentiation, and the guidance is direct.

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?

No annotations provided, so description carries the burden. It indicates the output is validated and uses the AWS Well-Architected model. It does not mention idempotency or side effects but given generation context, it's sufficiently transparent. Could mention if it modifies state.

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

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

Three sentences, front-loaded with the main action, then exclusions and alternatives. Every sentence earns its place; no fluff.

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?

Provides clear guidance on what the tool produces (nodes, edges), what it doesn't do, and where to go next. With only 2 parameters and no output schema, this is complete enough for correct agent 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 50% (existingNodes has description, prompt does not). The description mentions 'from a description' for prompt but doesn't add format or constraints. ExistingNodes is explained in schema. Description adds marginal value beyond 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?

Clearly states it generates a validated {nodes, edges} cloud architecture from a description using Pinpole's AWS Well-Architected model. Distinguishes from siblings by noting it does not draw and provides references to drawing and simulation tools.

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

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

Explicitly tells when not to use (does NOT draw) and directs to alternative tools: pass result to pinpole_draw_on_canvas or pinpole_simulate_cost, or use pinpole_build_architecture for combined step.

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?

No annotations provided, so description must disclose behaviors. It only states creation without mentioning side effects, permissions, idempotency, or error conditions.

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

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

The description is very short and front-loaded, with no wasted words. However, it could be slightly expanded to improve completeness without losing conciseness.

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

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

Given the simple parameters and sibling context, the description is minimally adequate but lacks info on return values or idempotency, which would be helpful without an output schema.

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

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

Schema coverage is 0%, and the description adds no information beyond parameter names (title, description). No explanation of constraints or usage for parameters.

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

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

The description clearly states the verb 'create' and resource 'new Pinpole project' with a brief purpose 'to hold architecture workspaces', distinguishing it from sibling tools like pinpole_create_architecture.

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 guidance on when to use this tool versus alternatives like pinpole_list_projects or pinpole_create_architecture. The description does not mention prerequisites or context.

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?

With no annotations, the description effectively discloses key behavioral traits: it creates project/workspace if missing, returns a canvas URL, and auto-layouts nodes left-to-right when positions are omitted. It does not mention authentication or destructive behaviors, but the provided info is sufficient for safe invocation.

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

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

The description is three sentences long, front-loading the main action, then mentioning the return value, and finally an important behavioral detail. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (4 parameters, nested objects, no output schema), the description adequately explains the input graph structure, side effects (creating project/workspace), auto-layout behavior, and the return URL. It provides enough context for an agent to understand the tool's purpose and usage.

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 compensate. It explains the overall graph structure, auto-layout behavior, and optional project/workspace IDs, but does not detail individual parameters like node properties or edge fields beyond what the schema names imply. This adds some meaning but not a comprehensive explanation.

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

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

The description clearly states the tool persists an architecture graph to the Pinpole canvas, distinguishing it from siblings like pinpole_build_architecture or pinpole_create_architecture which likely handle other aspects of architecture management.

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 indicates when to use this tool (to persist a graph to canvas) and mentions auto-creation of project/workspace if not provided, providing clear context. However, it does not explicitly mention when not to use it or suggest alternative tools, such as pinpole_create_architecture, which might be more appropriate for initial architecture creation.

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?

No annotations are provided, so the description must fully convey behavioral traits. However, it only states that the tool generates files and works offline. It omits critical details such as authentication requirements, whether existing files are overwritten, the output format, or any side effects. This leaves the agent with significant uncertainty about the tool's behavior.

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

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

The description is concise (two short sentences), but it sacrifices completeness for brevity. It front-loads the core purpose but omits necessary details, making it insufficiently informative for a tool with a complex input 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?

Given the complexity of the input schema (nested object with required fields) and the lack of an output schema, the description is incomplete. It fails to explain how to structure the architecture graph, what the output (Terraform files) entails, or any side effects. The agent cannot fully understand how to invoke the tool correctly without additional context.

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

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

The description provides no explanation of the single parameter ('graph'), which has a complex nested schema. With 0% schema description coverage, the description should elaborate on how to structure the architecture graph, but it only vaguely references 'from an architecture graph' without any specifics about node/edge properties, required fields, or examples.

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

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

The description clearly states the tool's purpose: generating Terraform project files from an architecture graph. It uses specific verbs ('Generate') and resource ('Terraform project files'), and the offline note distinguishes it from tools that may require network access. This effectively separates it from sibling tools like pinpole_build_architecture or pinpole_simulate_cost.

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

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

The description provides minimal usage guidance. It mentions 'Works offline' but does not specify when to use this tool versus alternatives, nor does it list prerequisites or exclusions. The agent is left to infer usage context from the tool name and siblings.

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?

No annotations are present, so the description carries full burden. It clearly states the operation is read-only (list) and specifies the output fields (id, title). No side effects or destructive behavior is implied. Could mention if data is paginated or ordered, but not required for basic transparency.

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

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

One sentence of 12 words, front-loaded with the action verb 'List'. No filler or redundant information. Every word 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?

Given the tool's simplicity (0 params, no output schema, no nested objects), the description provides all necessary context: what the tool does, for whom, and what it returns. No further information is needed 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?

The tool has zero parameters, and the schema coverage is 100% (empty object). The description adds nothing about parameters, but none are needed. Baseline for 0 params is 4.

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

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

The description clearly states the action (list), the resource (projects), and the scope (authenticated user's). It specifies the returned fields (id + title), effectively distinguishing it from creation or other tools. No ambiguity.

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 implicitly suggests use when needing a list of the user's projects, but it provides no explicit guidance on when to choose this tool over others, nor any context about prerequisites or alternatives. For a simple list, this is acceptable but not thorough.

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?

No annotations are provided, so the description bears full burden. It mentions reading local repo specs when available, but does not disclose whether the operation is read-only, any side effects, authentication, or rate 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?

Two sentences, no wasted words, front-loaded with primary purpose. 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?

For a simple list tool with no output schema, the description covers purpose and data source. However, it could specify output format or prerequisites for completeness.

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?

There are zero parameters, so baseline is 4. The description adds value by explaining the content and source behavior, which compensates for the lack of parameters.

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

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

The description clearly states that the tool lists AWS service ids/specs understood by the canvas, with specific verb 'List' and resource 'AWS service ids/specs'. It is distinct from sibling tools like pinpole_list_projects.

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

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

The description implicitly indicates this tool is for retrieving service specs, but does not explicitly state when to use it versus alternatives like pinpole_list_projects. The note about local repo specs provides some context.

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?

No annotations are provided, so the description must carry the burden. It states the tool returns a link, implying a read-only operation, but does not disclose side effects, authentication requirements, or rate 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?

The description is a single, focused sentence that clearly states the purpose without unnecessary words. It is front-loaded with the key action and outcome.

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?

Considering the tool's simplicity (two parameters, no output schema, no annotations), the description is nearly complete. It could mention that a URL is returned, but the purpose is sufficiently clear.

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 description only mentions 'project + workspace' without explaining the parameters in detail. It adds minimal meaning beyond the schema, failing to compensate for the lack of descriptions 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?

The description clearly states the tool returns a canvas deep link for a specific project and workspace, enabling the user to open the live diagram. It uses a specific verb ('Return') and resource ('canvas deep link'), distinguishing it from siblings like pinpole_draw_on_canvas.

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 guidance on when to use this tool versus alternatives. It does not mention when not to use it or compare with sibling tools such as pinpole_create_architecture.

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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It describes the tool as running a simulation and returning results, which implies no permanent side effects. However, it does not explicitly state that it is read-only or non-destructive, nor does it mention any potential resource intensity or limits. The description is adequate but leaves some behavioral aspects implicit.

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

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

The description consists of two concise sentences. The first sentence front-loads the action and key outputs, and the second sentence clearly states the use case. Every word earns its place, with no fluff 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?

Given the complexity of the tool (simulation over a graph with multiple traffic parameters), the description is somewhat brief. It does outline the main output categories (cost, latency, throughput, alerts), which is helpful, and there is no output schema to supplement. However, it does not explain how to interpret the output or any limitations (e.g., accuracy, underlying assumptions). The description meets the minimum requirements but leaves room for more detail.

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

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

The input schema has 0% documented description coverage for parameters, meaning the description must compensate by explaining the meaning and structure of parameters. The description mentions 'architecture graph' and 'traffic level' but fails to explain the nested structure of the graph (nodes, edges) or the traffic object (rps, duration, pattern). Users would need to infer parameter meanings from names alone, which is insufficient for a complex tool with nested objects.

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 starts with a specific verb 'Run' and clearly identifies the resource (simulation engine over an architecture graph at a given traffic level). It enumerates outputs (monthly cost, latency percentiles, throughput, alerts) and directly addresses the user's core question. This distinguishes it from sibling tools like pinpole_build_architecture or pinpole_create_architecture, which focus on architecture creation rather than simulation.

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 explicitly states the purpose: 'Use to answer what will this cost / how will it perform.' This gives a clear when-to-use context. It doesn't explicitly state when not to use or list alternatives, but the sibling tools (e.g., pinpole_build_architecture) suggest that this tool is specifically for simulation, not for building or exporting. The guideline is effective but could be more comprehensive.

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