PartForge

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

Annotations establish the safety profile (readOnlyHint=false, destructiveHint=true), and the description layers on genuinely non-derivable behavior: batch atomicity, the stale-hash conflict return shape ({conflict:true, manifest}), that nothing is persisted until the build succeeds, and the success/failure payload split (screenshot plus measure/verify/lint/match vs. build error plus lint findings). No contradiction with the destructive hint; the disclosure sharpens it.

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

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

Front-loaded with purpose, then ops, then hash contract, then return shapes — a logical progression with no filler sentences. It is dense and long, but nearly every clause carries operational information; the only mild cost is that the conflict and empty-tree rules are packed into the same paragraph.

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

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

With no output schema, the description carries the return-value burden and does so for both success and failure paths, including the null-verdict cases that the annotations cannot express. For a destructive, 5-parameter mutation tool, nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 80% and the schema already documents checks, count, old_str and forgeId in detail, so the baseline is 3. The description still adds real value by stating the preference ordering among ops, the exact-once-by-default semantics of old_str, and the required provenance of expectedTreeHash.

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

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

Opens with a specific verb+resource+side effect: 'Apply an atomic batch of exact edits to a forge's tree, then build it.' It also differentiates itself from siblings by naming get_forge and read_part_files as the source of expectedTreeHash, so an agent knows exactly which tool this is and where its inputs come from.

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 selection rules across the four ops (prefer str_replace with a unique old_str, use create for new files, delete to remove, write only as a whole-file fallback) and states the no-code case (treeHash null → first call creates part.js with an empty expectedTreeHash). It also routes the agent to the right sibling for obtaining the hash.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write. The description adds genuine behavior beyond that: the forge starts empty, is private by default, and gets named at first build. It doesn't cover duplicate-name behavior, quotas, or whether the operation is reversible.

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 front-loaded sentences with no filler; the lifecycle fact and the default-name rule each earn their place. The parenthetical about empty expectedTreeHash is mildly tangential but useful for chaining into apply_part_changes.

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

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

For a one-parameter creation tool with no output schema, the description covers purpose, initial state, and parameter behavior. It never indicates what the response yields (e.g. a forge identifier needed by get_forge or apply_part_changes), which is the one 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 coverage is 0%, so the description must carry the single parameter — and it does: `name` is optional, bounded at 1–120 characters, and defaults to 'Untitled forge'. Only uniqueness or character restrictions are left unspecified.

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 ('Start a new, private forge') and immediately clarifies the initial state, which separates it from apply_part_changes. The 'private' qualifier is meaningful given that make_forge_private and publish_forge exist as siblings.

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?

Implies the trigger condition (you need a brand-new private forge) and explains the follow-up step by naming apply_part_changes as the call that gives the forge code. It stops short of explicit exclusions, e.g. that renaming later goes through update_forge_details rather than this tool.

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 a non-destructive, open-world mutation. The description adds real value on top: the source is the Google Fonts catalog (consistent with openWorldHint), the effect is attaching a source file to the forge, and the return is a pfc-asset:// token — notable since there is no output schema. Gaps remain on failure behavior (unknown family) and whether repeated calls duplicate assets.

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

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

Three tight sentences, front-loaded with the action and scope, followed by the integration token and the per-parameter clarifications. No filler or repetition of 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?

For a 3-parameter mutating tool with no output schema and only 33% schema coverage, the description covers purpose, return value, and post-call usage adequately. It leaves edge cases (invalid family, variant format, re-fetch/idempotency) unaddressed but is otherwise sufficient to call the tool correctly.

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

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

Schema coverage is only 33% (only forgeId is documented), so the description must compensate, and it largely does: `family` is defined as the catalog family name with an example ('Roboto') and `variant` is said to default to regular. It stops short of giving the accepted variant syntax (e.g. bold/italic vs numeric weight).

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 ('Fetch an open-licensed font from the Google Fonts catalog') plus its side effect ('attach it to a forge as a source file'). No sibling tool deals with fonts, and the downstream linkage (pfc-asset:// token, k.text2d rendering) makes the intent unmistakable.

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?

Tells the agent exactly where the result goes: declare the returned token in the part's `fonts:` field, then use it in k.text2d. That is clear contextual guidance for when this tool is needed, but there is no explicit when-not or named alternative for obtaining fonts by other means.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds content-level context (failure modes and fixes, the edit dialect) but says nothing about the guide's format, size, or caching behavior; with annotations carrying the behavioral load, a 3 is appropriate.

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

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

A single sentence, front-loaded with the imperative and its trigger condition, followed by a tight enumeration of contents. Every clause earns its place 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?

For a parameterless doc-fetch tool this tells the agent both when to call it and what it will find, which is nearly complete. Since no output schema exists, the description could ideally note the return format (e.g., markdown/text), which is the only remaining 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of apply_part_changes' 'edit dialect' is useful forward-looking context but is not a parameter 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?

States a specific verb ('Read') and resource ('PartForge's authoring guide') and then enumerates the guide's contents (layout, operations, edit dialect, failure modes). This is clearly distinguishable from generic siblings like read_docs or search_docs because it is scoped to forge authoring.

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 timing: 'before writing or editing any forge's code,' which routes the agent correctly relative to create_forge and apply_part_changes. It does not, however, name when a sibling (e.g., read_docs/search_docs for non-authoring topics) is the better 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by enumerating the returned payload (manifest, digest, tree hash, revision, license, links), which is useful given there is no output schema, but it says nothing about auth needs, error behavior, or the single-forge lookup mechanics.

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

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

A single front-loaded sentence with an informative field enumeration and no filler. The list is long but each item is meaningful; nothing reads as padding.

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

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

For a read-only single-get tool whose annotations cover safety and whose single parameter is fully schema-documented, the description is adequate and usefully enumerates returns in the absence of an output schema. Its main shortfall is not clarifying its relationship to show_forge, leaving a genuine ambiguity for tool selection.

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

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

Schema description coverage is 100% and the forgeId field is fully documented in the schema ("id or its slug, exactly as list_forges or get_forge returned it"). The description adds no parameter-level detail beyond this, so the baseline 3 applies.

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

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

States a specific verb ("Read") and resource ("one forge") and enumerates the returned content, which lets an agent understand scope. However, it never distinguishes itself from its sibling show_forge, which appears to overlap, so the boundary is left to 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?

"Read one forge in full" implies fetching a single forge by id, but there is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as list_forges or show_forge. With a near-duplicate sibling present, this absence is a real gap.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only the account scoping; it says nothing about result ordering, pagination, or how the single limit parameter affects output.

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 front-loaded sentence with an inline jargon definition that genuinely helps an agent understand the resource. 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?

A simple read-only list tool whose annotations cover the safety profile, so the description is nearly sufficient. However, with no output schema the agent gets no hint of what a forge record contains, and the limit parameter's behavior is left unexplained.

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

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

Schema description coverage is 0% for the lone 'limit' parameter, and the description never mentions it or its 1-100 range. It adds no meaning beyond the property name, so it does not compensate for the coverage 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 (List) and resource (forges) and helpfully defines the domain jargon as a 3D-printable part project scoped to the account. It doesn't explicitly contrast with the get_forge/show_forge siblings, but the action itself 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?

There is no when-to-use guidance, no mention of alternatives like get_forge or show_forge, and no note about pagination or empty results. Only the fact that it operates on 'this account' hints at scope.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so safety is already flagged; the description adds the crucial scope of that destruction — visibility is restricted to the owner rather than content being deleted. It still omits reversibility (can it be republished?) and any permission requirements for the caller.

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

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

A single tight sentence with the action front-loaded and the resulting state appended; no wasted words.

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?

Complete for a single-parameter state-change tool: schema is fully documented and no output schema exists, so return-value explanation is unnecessary. The only gap is that an agent gets no signal about reversibility or re-publishing before committing a destructive change.

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

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

Only one parameter exists and schema description coverage is 100%, including guidance that the id or slug comes exactly from list_forges/get_forge. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

Names a specific verb+resource ('Make a forge private') and states the resulting scope ('only its owner can see it'). This inherently distinguishes it from the inverse sibling publish_forge without 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?

Implies the precondition that the forge is currently published ('published forge private again'), which is useful. However, it never states when-not to use it or names the counterpart tool (publish_forge) for re-publishing, leaving routing 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?

Beyond the destructive/openWorld annotations, it discloses the preview-then-commit mechanics, the token lifetime (10 minutes), the invalidation condition (only while the forge is unchanged), and the concrete scope of destruction (replacing existing public content). The conditional-token behavior is the kind of trait annotations cannot express.

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 outcome, then the ordered steps, ending with the safety constraint. Five sentences, each carrying distinct operational information; nothing is redundant with 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?

There is no output schema, but the description compensates by describing what the preview returns (a description of what would change and a confirmToken). Combined with the explicit flow, an agent has everything needed to execute both calls 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 100%, so the schema already documents both fields; the description nonetheless adds real semantics — that omitting confirmToken yields a preview plus a token, and that the token expires and is invalidated by forge changes. It lightly augments rather than merely repeats 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 — make a forge public at its partforge.ai page — and immediately frames the effect as replacing what visitors currently see. This clearly distinguishes it from the sibling make_forge_private without needing to open either schema.

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

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

Explicitly prescribes the two-step protocol: call with only forgeId to preview, show the user, get confirmation, then call again with confirmToken. It also states a hard prohibition ('Never send a confirmToken the user has not explicitly agreed to in this conversation'), which is exactly the when-not-to guidance an agent needs.

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

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

Annotations already declare readOnlyHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavior beyond that: a max of 4 ids per call and partial-failure semantics where unknown ids are returned in unknownIds rather than failing the whole call. It stops short of describing ordering or full return shape, but the error-tolerance disclosure is real value.

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

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

Three sentences, front-loaded with the core action and limit, followed by id sourcing and then the failure-mode note. No filler and every sentence carries distinct information.

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

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

There is no output schema, so the description must hint at returns; it does so by naming the unknownIds field for failed ids. Combined with id sourcing, the 4-item cap, and the when-to-use rule, an agent has everything needed to call 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% for the single required 'ids' parameter, so the description must carry the load and largely does: it tells the agent the values are section ids, where to obtain them (search_docs or a topic index), and the 4-item ceiling. It does not give id format examples, but the semantic guidance is substantially better than the bare 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 ('Read PartForge documentation sections in full, by id') plus a hard bound ('up to 4'). It also implicitly separates itself from the sibling search_docs by explaining that search_docs is where the ids come from.

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

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

Explicit when-to-use: before invoking any operation whose options or semantics are uncertain, and explicitly says never to guess a method name. It also names the sibling alternative (search_docs) and the topic-index fallback as the id sources.

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/openWorld/destructive hints, yet the description goes further and discloses real behavioral traits: a per-call cap, files returned in `skipped`, and a single oversized file coming back cut short in `truncated`, with the remedy for each. This is exactly the value-add beyond annotations.

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

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

Front-loaded with the core action, then mode selection, then failure/recovery behavior, then the editing precondition. Every sentence carries distinct information with no filler.

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

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

No output schema exists, so the description carries the return-value burden — and it explains the cap, `skipped`, and `truncated` results. Combined with the read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is only 33% (only forgeId documented), so the description must compensate — and it does, defining `paths` as complete files and `views` as 1-indexed line-numbered windows capped at 200 lines. It adds real meaning the schema lacks, though line-window edge behavior isn't fully specified.

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: 'Read file contents from a forge's current tree.' The scoping to the forge's current tree distinguishes it from sibling readers like read_reference_part and the search_part_files/search_reference_parts searchers.

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 mode selection ('Use `paths` for complete files or `views` for windows') and a clear lifecycle trigger ('Call this before editing any file you have not already read'). It routes between its own parameters well, though it never names a sibling tool as an alternative.

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

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

Adds substantial behavior beyond the readOnly/openWorld annotations: provenance lines with licensing terms (own-forge files reusable, keep provenance on library copies, never copy 'reference only' files), a prompt-injection warning to treat library source as data, and the non-obvious rule that an excluding switch refuses the call rather than returning a plain not-found.

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

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

Front-loads the core action before the caveats, and every sentence carries distinct information (paths override, provenance/licensing, injection warning, forgeId). It is dense and em-dash heavy, but nothing reads as filler.

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

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

With no output schema, the description still explains the return ('file manifest plus the entrypoint; each manifest entry carries exports and summary'), and it covers licensing, safety, and the forgeId scoping behavior. Nothing an agent needs to invoke it correctly appears 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 only 33% (forgeId alone is documented), so the description compensates by defining id (a search_reference_parts hit), paths (file paths whose exports you want, capped at 10), and forgeId's switch-sensitive semantics. It adds real meaning, though it doesn't describe the id's format or edge cases.

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 source of one part ... by id') and explicitly scopes it to a search_reference_parts hit, which separates it from the sibling search_reference_parts (which finds hits) and read_part_files. An agent can identify the tool's role 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 clear operational guidance: ids come from search_reference_parts, and callers should pass paths (up to 10) naming files whose exports they want 'instead of reading the entrypoint blind,' plus how to use forgeId. It stops short of an explicit when-not-to-use or a direct comparison against read_part_files.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a 'realistic' request can't actually render materials here and returns a CAD image plus an explanatory note, which sets correct caller expectations.

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?

Single tight paragraph, front-loaded with the action and return value, then parameter detail. The parenthetical about PartForge's lack of a live browser is slightly long but earns its place by explaining the fallback.

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 render tool whose annotations cover safety and whose output is images rather than structured data, the definition is nearly complete: it explains what is returned, the angle options, and the appearance fallback. Lacks only an explicit steer on sibling alternatives.

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 only 33% schema description coverage, the description carries the load for `views` and `appearance`. It adds genuinely useful detail the schema lacks: the default view set (iso, front, top) and the default appearance (cad). The max-6 constraint is redundant with the schema but harmless.

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: render a forge's saved tree from canonical camera angles and return images. Clear enough to distinguish from sibling rendering/viewer tools like show_forge or viewer_load_forge without opening either schema.

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

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

Gives invocation-relevant context (default views, max 6, appearance options, fallback behavior) but never explicitly says when to choose this over sibling tools such as show_forge or viewer_load_forge. Usage is implied rather than stated.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds real behavior: the issue goes to the team rather than the user, a repeat within a day is silently dropped rather than filed, details' first line becomes the title, and user code/messages must not be quoted. That is substantive disclosure beyond the structured fields.

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

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

Front-loads the single most important fact (recipient routing) and wastes no sentence, but the enum definitions and exclusions run together as one dense block rather than being segmented, making a long description slightly harder to scan than necessary.

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

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

No output schema exists, yet the description needn't explain a return value since submission is fire-and-forget; with annotations, full parameter meaning, dedup behavior, and prerequisites all covered, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is only 25% (kind and toolName carry no schema description), so the description must compensate and it does: all four enum values are defined by trigger scenario, details is broken into three required parts with a title-derivation rule, and forgeId/toolName are scoped to what they name.

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

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

States a specific verb (file a note) plus the exact recipient and the critical non-recipient: 'to the PartForge team — never to the user.' No sibling tool does anything similar, and the routing constraint alone distinguishes it from the whole list.

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

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

Gives the four trigger conditions in full, then explicit exclusions ('Do not file for: the user changing their mind, a limit a tool result already explained...'), a sequencing prerequisite ('Only after you have already worked around the problem'), and dedup policy. This is a complete decision rule, not a hint.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the matching behavior (case-insensitive by default) and the return shape (bounded line-numbered windows tagged with the section id), which is real behavioral context beyond the annotations.

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

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

Three tight sentences, front-loaded with the search scope, then behavior, then the operational trigger. Every clause carries information and nothing is padded.

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

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

For a read-only search with no output schema and no annotations gaps, the description covers scope, matching mode, and return format adequately. It stops short of explaining the maxResults/contextLines parameters, which slightly weakens completeness against a 0%-coverage 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 description coverage is 0% across four parameters, and the description only compensates by stating the caseSensitive default. 'Bounded line-numbered windows' loosely gestures at maxResults and contextLines but gives no ranges or meaning, leaving most parameters unspecified.

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 (Search), the exact resource (complete PartForge documentation, enumerated as authoring guide, error catalogue, worked examples), and the match mode (literal string). An agent can distinguish it from read_docs, which consumes the returned section id rather than performing lookup.

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 trigger ('On any build failure, search the error text here first') and explains the handoff to read_docs via the returned section id. It does not explicitly contrast with siblings like get_authoring_guide or search_part_files, so the routing 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 readOnlyHint, destructiveHint=false, and a closed-world scope, so the safety profile is covered. The description adds real behavior beyond that: case-insensitive default matching, bounded line-numbered context windows, and a truncation flag. Return formatting is not fully detailed, keeping it below 5.

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

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

Two sentences, zero filler, with the core operation stated first and the downstream use case second. Every clause carries information.

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

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

There is no output schema, and the description does cover the return shape (bounded line-numbered context windows, truncated flag), which is the key completeness burden here. It omits guidance on the paths scoping parameter and result limits, so it is strong but not fully self-sufficient for a 6-parameter tool.

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

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

Schema description coverage is only 17% (only forgeId is documented), so the description must compensate. It clarifies the caseSensitive default ('Case-insensitive by default') and alludes to contextLines and maxResults via 'bounded line-numbered context windows' and 'truncated flag', but leaves the paths filter and result-count semantics 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?

States a specific verb and resource ('Find a literal string in a forge's current tree') plus a scope qualifier ('without reading complete files') that distinguishes it from the read_part_files sibling. An agent can identify the operation 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 an explicit use case and routes to a sibling: 'Use this to locate an anchor for apply_part_changes' str_replace.' That is actionable context. It stops short of stating when NOT to use it (e.g., prefer read_part_files when the whole file is needed), so it is not a full 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 only declare readOnly/openWorld/destructive, so the description carries the behavioral load and does so richly: returns metadata only, never source; results carry modules with exported names and first comment line; own hits are ranked first and marked own:true; forgeId can narrow either corpus or cause a refusal if both switches are off; and a prompt-injection warning about user-authored titles/summaries/tags. This is far beyond what the annotations provide.

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

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

Purpose and the source-vs-metadata distinction are front-loaded, and each sentence conveys distinct operational detail. It is dense and long for a single paragraph, but almost no sentence is redundant, so it avoids a lower score.

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

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

With no output schema, five parameters, and low schema coverage, the description fills the gaps: it describes the return shape (metadata, modules with exported names and comment line), the ranking/own marking, scoping rules, refusal conditions, and the safety caveat. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is only 20% (just forgeId), so the description must compensate and largely does: it explains query's omit-to-list behavior, forgeId's scoping semantics, and vendorable's default-true widen-to-non-copyable behavior, plus references tags indirectly. Only limit is left unexplained, keeping it short of 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 ('Search published public forges to use as reference') and clarifies the nature of the content ('real, working examples of how similar geometry is structured and parameterized'). It also differentiates itself from siblings by naming read_reference_part as the follow-up for source. An agent can distinguish it from list_forges and search_part_files without opening any schema.

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

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

Explicitly covers when to omit query ('Omit query to list everything'), what happens without forgeId versus with forgeId, and when to pass vendorable:false. It names the follow-up tool (read_reference_part) and the scoping alternative, leaving little to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add behavior — and it does: the viewer renders inline in chat, is interactive (orbit plus a settings panel), and stays live and self-updating so repeat calls are unnecessary. This idempotence/auto-refresh detail is real behavioral value not present in the annotations, though permissions or failure modes are not discussed.

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

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

Three tight sentences: what it does first, then the trigger conditions, then the anti-trigger with its reason. No filler, nothing buried, and the most important constraint 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?

For a one-parameter, no-output-schema tool whose result is a UI surface rather than data, the description covers everything an agent needs: what appears, where it appears, that it is interactive, and when to invoke or skip it.

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

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

Schema description coverage is 100% and the single forgeId parameter is already documented with its accepted forms and the source tools that return it. The description adds no parameter-level syntax or format information beyond that, so the baseline 3 applies.

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

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

States a specific verb (Show) and resource (a forge) plus the delivery surface (PartForge's live 3D viewer, inline in chat) and what the user can do with it (orbit, try settings). An agent understands the action immediately. It does not, however, name or distinguish itself from nearby siblings such as viewer_load_forge or viewer_forge_status, which is the only thing keeping this from 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 explicit when-to-use conditions (after a forge's first successful build; whenever the user asks to see the forge) and an explicit when-NOT-to (don't call after every edit, because an open viewer self-updates). That is strong, actionable routing guidance. It stops short of a 5 only because it never names an alternative tool for the cases it excludes.

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 openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it never says whether omitted fields are preserved or cleared, whether values are replaced wholesale, or what authorization is required — a material gap for a destructive update.

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

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

A single front-loaded sentence that names the action and the affected fields with zero filler. Nothing 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?

For a destructive mutation with no output schema and 20% parameter coverage, the description omits permission requirements, overwrite/merge behavior, and any indication of what the call returns on success. An agent cannot call this with confidence.

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 only 20% (just forgeId is documented). The description enumerates the four optional fields, but this merely echoes the schema property names and supplies no format, constraint, or merge/replace semantics for name, tags, license, or 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?

States a specific verb and resource ('Change a forge's name, description, tags or license') and scopes it to listing fields, which separates it from siblings like create_forge, publish_forge, and make_forge_private. It stops short of explicitly naming an alternative, so it is clear but not fully differentiated.

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?

Only implies usage via 'the fields shown on its listing.' There is no statement of when to use this versus make_forge_private, publish_forge, or create_forge, and no prerequisites (ownership/permission) are given.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: the viewer polls it every few seconds to detect edits and trigger rebuilds. It could add rate-limit or auth context, but the polling and caller restriction are meaningful.

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 sentences with zero waste. The return value is front-loaded, and the caller restriction follows immediately.

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 one-parameter read-only status tool, the description is complete: it states the return fields, caller restriction, and polling purpose. Annotations handle the safety profile, and no output schema is needed because the returned fields are named.

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

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

Schema coverage is 100% and the sole forgeId parameter is fully documented in the schema, including acceptable id or slug forms. The description adds no further parameter syntax or format details, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: returns a forge's current name and tree hash. The description also distinguishes this as a viewer-internal status endpoint rather than an assistant-facing forge query, helping separate it from siblings like get_forge or show_forge.

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

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

Explicitly states who calls it ('Only the viewer calls this') and who should not use it ('it is not a tool for the assistant'). This is direct when/when-not guidance that prevents miselection.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely useful context: the write creates a *new revision* rather than mutating in place, and it is invoked only by the viewer UI. It does not explain the concurrency semantics of expectedTreeHash or what happens on a hash mismatch, which is a real gap for a write operation.

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

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

Two sentences, front-loaded with the action and outcome, followed by the routing constraint. No filler and every clause carries information.

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

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

There is no output schema, so return values need no explanation, and the viewer-internal framing is fully covered. However, with three required parameters and only one documented, the definition leaves the agent without an understanding of how values is shaped or what expectedTreeHash enforces.

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 only 33%: forgeId is documented but values and expectedTreeHash are not. The description loosely maps 'panel values' onto the values parameter, but expectedTreeHash — an apparent optimistic-concurrency token — is entirely unexplained in both schema and description, so it fails to compensate for the coverage 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 precise verb+resource+outcome: it saves the panel values chosen in the PartForge viewer as the forge's new default settings, written as a new revision. It also distinguishes itself from the sibling that performs a superficially similar job (apply_part_changes), so an agent can route correctly without opening a schema.

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

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

It explicitly names when the tool fires (when the person presses Keep in the viewer) and, more importantly, when NOT to use it — 'it is not a tool for the assistant' — and names the alternative (apply_part_changes) for editing defaults. This is the strongest form of routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral trait beyond the annotations: this tool is invoked only by the viewer, not by the assistant, which is exactly the context an agent needs to avoid misusing it. It stops short of describing failure modes or what the viewer does with the result.

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, zero filler. The purpose is front-loaded and the restriction plus alternative follow immediately; every 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?

For a single-parameter read tool with no output schema, the description covers what is read (code files and tree hash) and who may call it. Return-shape details are arguably unnecessary here, though a brief note on error behavior when the forge is missing or the viewer has no session would round it out.

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

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

Schema description coverage is 100% and the single forgeId parameter is well documented in the schema (id or slug, as returned by list_forges or get_forge). The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a precise verb and resource — reads a forge's code files and tree hash for the PartForge viewer to build and display it. It also distinguishes itself from the assistant-facing sibling by naming read_part_files, so the agent can route correctly without opening a schema.

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

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

Gives an explicit when-not ('Only the viewer calls this; it is not a tool for the assistant') and names the alternative to use instead ('use read_part_files instead'). Nothing about tool selection is left to inference.

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