Picorn

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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower; the description adds real value by disclosing the token requirement and the graceful-degradation behavior ("without one it explains how to connect"). It stops short of describing pagination or the exact response shape, but neither is materially relevant here.

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 tight sentences, front-loaded with what the tool shows before the prerequisite. No filler, no repetition of the title.

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

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

For a zero-param read-only tool with an accurate readOnly annotation, the description covers what it does, what it surfaces, the auth requirement, and the failure path. Nothing an agent needs to invoke it correctly is missing.

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

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

There are no parameters, so the baseline is 4; the description correctly adds no parameter guidance because none is needed.

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 precise resources (the connected Picorn account and its linked social media accounts). It is easily distinguished from siblings like picorn_social_accounts_connect, which mutates state, whereas this only reports it.

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

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

Gives a clear precondition — a personal Picorn access token is required — and states the fallback behavior when it is missing. It does not explicitly name an alternative sibling to use, but for a zero-param read-only status tool the usage context is unambiguous.

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

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

With only readOnlyHint/openWorldHint to work from, the description carries the burden well: it says no model is called during compile, that real fonts are measured and asset libraries searched, that patches reuse cached searches, and that generation requires a connected account with credits at 1.2x fal price with per-blueprint caching. These are concrete cost, caching, and side-effect disclosures 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?

The core compile/patch purpose is front-loaded in the first sentence, and subsequent sentences are information-dense rather than padded. It is long and slightly nested around the generation-line syntax, but virtually every sentence carries actionable detail.

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 complex compile/render tool with no output schema, the description enumerates exactly what comes back (blueprintId, coded errors/warnings with fixes, scene report, ASCII wireframe, canonical source, inline preview) and describes the iteration loop to errors=0. Nothing essential is left for the agent to infer.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds genuine meaning: it explains the blueprintId+patch interplay, the standalone blueprintId behavior, and the speed tradeoff of preview:false. This goes beyond the terse property 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 states a specific verb and resource — compile a PBL document or apply patch lines to an existing blueprintId — and clearly delineates the two modes of operation. An agent can distinguish this from siblings like picorn_render_svg or the editor_* tools 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?

It gives explicit routing rules: use pbl for a new compile, blueprintId+patch to iterate, blueprintId alone to re-fetch the current revision, preview:false for a text-only check. It also names the sibling (picorn_search_library) and states the condition under which generation lines should be used at all ('Library first').

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 readOnlyHint=false and openWorldHint=true; the description adds real behavioral context — that the file is persistent and editable, that it renders every slide, that an access token determines whether it lands in your account, and that it returns editorUrl/render URLs/contact sheet. It does not cover idempotency or duplicate-file behavior, but it goes well beyond the annotations.

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

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

Front-loads the core transformation and its output, then adds the account/campaign/scheduling nuance in the second sentence. Dense but every clause carries information; the single long first sentence is the only mild readability cost.

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

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

For a mutation tool with no output schema, the description usefully enumerates the returned artifacts (editorUrl, render URLs, contact sheet) and the side effects on the account. The remaining gap is the undocumented workspace scoping parameters, which the description never explains.

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 22% across 9 parameters, so the description has to compensate and only partly does: it clarifies blueprintId, campaignId + ideaId, and (implicitly) caption. tags, title, workspaceProjectId, and workspaceProjectKey are undocumented in both schema and description, leaving real gaps, though allowErrors and caption do carry inline schema descriptions.

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 ('Turn a compiled blueprintId into a persistent, fully editable Picorn editor file') and immediately scopes it against the upstream compile step and the downstream editor artifact. An agent can distinguish this from picorn_blueprint_compile and picorn_editor_create_project without opening a schema.

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

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

Clearly implies the prerequisite (a compiled blueprintId) and names the downstream pairing with picorn_posts_schedule plus the campaignId + ideaId linkage context. It stops short of explicitly saying when *not* to use this versus editor_create_project or what to do if no compile exists yet.

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, openWorldHint=false), lowering the bar. The description adds that the samples 'compile with 0 errors', a useful quality guarantee, but says nothing about how many examples are returned, their format, or ordering.

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, front-loaded with what is returned and then how to use it. Every clause earns its place, including the parenthetical taxonomy of example types.

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 parameters, no output schema, and read-only annotations, the description carries most of the burden and does describe the shape of the returned content. It stops short of stating count, format, or whether the examples are static, 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?

The tool takes no parameters, so there is no schema to clarify and the baseline is 4. Nothing in the description conflicts with the empty input 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 states a specific verb ('Return') and resource ('reviewed PBL showcase posts') and enumerates the four example types it yields, making the tool's output concrete. It is distinguishable from sibling blueprint tools like picorn_blueprint_compile, though it never names an alternative explicitly.

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

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

It gives clear intended usage ('Use them to learn proven structure, spacing and effect choices') and a do/don't boundary ('write new copy, colours and fonts from the brief instead of reusing theirs'). It lacks any explicit comparison to sibling tools such as blueprint_spec or blueprint_compile, so routing is inferred 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 already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description usefully adds that the return is a static document with a fixed set of sections. It also clarifies a behavioral boundary agents would otherwise guess at: geometry is handled by the engine with real fonts, so PBL text does not need to encode measurements.

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 return payload, then the usage trigger, then supporting context about the language. Four short sentences with little waste, though the closing sentence about font measurement and geometry is only tangentially necessary for deciding to call the tool.

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 zero parameters, no output schema and annotations covering the safety profile, the description carries the remaining burden well: it says what comes back, what the language is, and when to read it. An agent has everything needed to decide to call 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?

The tool takes no parameters (empty schema), so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a single fixed output with no arguments to tune.

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

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

The description uses a specific verb ("Return") and names the resource precisely (the complete Picorn Blueprint Language spec), then enumerates its contents: syntax, design rules, a full example and repair patch rules. That is well beyond a tautology. It stops short of a 5 because it does not differentiate itself from the sibling picorn_blueprint_examples, which plausibly overlaps with the "full example" content claimed here.

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 it once before writing PBL" gives an explicit trigger condition tied to a downstream activity, which is exactly the guidance an agent needs for a spec-fetch tool. It does not, however, name alternatives (e.g. picorn_blueprint_examples for examples, picorn_capabilities for capability discovery) or state when this tool is unnecessary.

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 readOnlyHint=false and openWorldHint=false; the description adds material context beyond that — the auth requirement (Picorn access token), the implicit side effect of creating a project when the workspace params are omitted, and the mutation's output identity (campaignId plus one ideaId per idea). This is more than the annotations convey.

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

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

Dense but front-loaded: purpose first, then the workspace decision, then the return values, then the downstream workflow. Every sentence adds operational information — the parenthetical "(no model is called)" and the access-token note both prevent a wrong assumption.

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 helpfully states what is returned (campaignId, ideaId per idea), and it covers prerequisites and the next tool in the chain. It stops short of describing the boundary conditions an agent might hit, such as the 50-idea cap or how ideas are handled if the array is omitted.

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

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

Schema description coverage is only 20%, so the description must compensate — and it does for the two hardest parameters, explaining the source of workspaceProjectId/workspaceProjectKey and the semantics of omitting both. It does not explain the ideas array's fields (hook, cta, angle, title, caption) or the topic/description semantics beyond the general phrase "post ideas," leaving part of the low-coverage schema undocumented.

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

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

States a specific verb and resource ("Create a campaign") and immediately scopes it as built "from agent-authored post ideas (no model is called)," which distinguishes it from generation-oriented siblings like picorn_generate_image. The clarification that no model is invoked separates it from anything that produces content on the server side.

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

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

Gives explicit conditional guidance: pass workspaceProjectId + workspaceProjectKey from picorn_projects_create, or omit both to create a new project named after the topic. It also names the follow-up step (create post files, then picorn_posts_schedule), so the agent knows both prerequisites and downstream alternatives without inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the auth requirement ('Requires a Picorn access token') and the shape of what is returned. It stops short of describing error behavior or what 'linked file IDs' concretely are.

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

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

Two short sentences, front-loaded with the core action and return contents, with no wasted phrasing. The auth note is terse and earns its place as a prerequisite.

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

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

For a one-parameter read tool with no output schema, the description carries the return-shape burden and partially discharges it (ideas, linked file IDs) while noting auth. It omits how the required campaignId is sourced and any error/empty-result behavior, leaving modest gaps.

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

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

Schema description coverage is 0% for the single campaignId parameter, so the description must compensate and does not: it never states that the argument is a campaign identifier, its format, or how to obtain one (e.g., from picorn_campaigns_list). 'One campaign' only weakly implies the parameter's role.

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 one campaign') and adds the return contents ('its ideas and linked file IDs'), which lets an agent separate it from picorn_campaigns_list (many) and picorn_campaigns_create (write). It is clear without explicitly naming the siblings it differs 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?

Usage is only implied: 'read one campaign' suggests fetching a single campaign by ID as opposed to listing. There is no explicit when-to-use statement, no named alternative, and no exclusions, so an agent must infer the selection condition from the sibling names.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds a real behavioral fact on top: the required Picorn access token. It also discloses the shape of the returned payload (campaigns with nested ideas and linked files), which matters because no output schema exists.

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 wasted words: the first states what is listed and what comes back, the second states the auth prerequisite. Nothing could be cut without losing information.

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

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

For a zero-param, read-only list tool with no output schema, the description covers the essentials: what is returned, its nesting, and the token requirement. It stops short of mentioning pagination or result-size behavior, which is the only meaningful 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 the baseline is 4. The description correctly implies a no-argument, user-scoped listing ('the user's campaigns') rather than misleading the agent into looking for filter inputs.

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

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

States a specific verb and resource ('List the user's campaigns') and goes further by naming the nested payload it returns (ideas and the files linked to each idea). That distinguishes it from picorn_campaigns_create and picorn_campaigns_inspect, though it never names those siblings outright.

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

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

No when-to-use guidance and no alternatives named. An agent reading 'list' would reasonably default here over picorn_campaigns_inspect, but nothing in the text confirms that choice or states any preconditions for calling it.

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 and openWorldHint, so the bar for added behavior context is lower. The description adds 'live' (suggesting real-time data) and 'fair-use limits' (implying quota awareness), which are useful behavioral disclosures beyond the annotations. No contradiction exists.

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, compact sentence that front-loads the verb and clearly itemizes the output categories. Every word adds value, with no redundancy or 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?

Given no parameters, no output schema, and a simple listing behavior, the description covers the essential information. It names all the capability categories returned, which is sufficient for a tool of this simplicity. It does not describe the response structure, but that is not critical for a capabilities list.

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% (trivially). Baseline for zero parameters is 4. The description does not need to compensate for missing schema details, and it appropriately describes what the tool lists.

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 function with a specific verb 'List' and explicitly enumerates the resource categories (canvas formats, fonts, layouts, image models, GPU reachability, fair-use limits). This distinguishes it from sibling tools which are all action-oriented (design, edit, render, etc.).

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

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

The description implies usage as a discovery/preflight tool (e.g., to check available formats or limits before other operations), but it does not explicitly state when to use it or mention alternatives. No exclusions or contextual triggers are provided, leaving usage mostly implicit.

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 indicate readOnlyHint=false and openWorldHint=true, and the description adds meaningful behavioral context: it resolves declared placeholders, renders through Fabric/SVG, and does not call an internal language or design model. This goes beyond the annotations by explaining the rendering pipeline and the absence of a design model, which helps the agent understand what happens when the tool is invoked.

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 two sentences with no wasted words. It front-loads the critical constraint (CODEX-ONLY) and the core behavior (resolves placeholders, renders through Fabric/SVG), then clarifies what it does not do. 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 tool with 4 parameters, 1 required, and no output schema, the description covers the essential behavioral context: what input is expected (complete SVG), what happens (placeholder resolution, rendering), and what is not involved (no internal design model). It doesn't describe return values or error conditions, but the absence of an output schema and the simplicity of the tool make this acceptable. The description is complete enough for an agent to select and 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 description coverage is 50%, with the 'svg' and 'preview' parameters described in the schema. The description adds context about the SVG being complete and Codex-authored, which reinforces the 'svg' parameter's meaning. However, it doesn't add detail about 'width' or 'height' beyond the schema's numeric constraints, and the description doesn't compensate for the undocumented parameters. 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 the tool's purpose: it renders a Codex-authored finished design by resolving placeholders and rendering through Fabric/SVG. It explicitly distinguishes itself from other tools by noting it is CODEX-ONLY and that no internal language or design model is called, which differentiates it from siblings like picorn_edit_image or picorn_generate_image.

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 clear context for when to use this tool: when Codex supplies the complete SVG. It doesn't explicitly name alternatives or exclusions, but the CODEX-ONLY marker and the contrast with 'no internal language or design model is called' imply it should be used instead of generation or editing tools. It could be stronger with explicit when-not-to-use guidance, 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.

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description goes well beyond that by disclosing the credit requirement, the 1.2x fal markup, and the return payload (inline preview, public imageUrl, chargedCents). It does not cover failure modes, size limits, or latency, so not a 5.

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

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

Three tightly packed sentences: purpose and capability list first, input sourcing second, cost and return values last. No filler, no repetition of the title, and the most decision-relevant facts are 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 4-parameter paid mutation with no output schema, the description supplies the auth/cost context and describes the return payload, which is exactly what is missing from structured fields. Gaps remain around the undocumented 'preview' parameter and error/limit behavior, but an agent can invoke it correctly from this text.

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% (only 'prompt' is documented), so the description must compensate - and it does for the two image inputs, explaining that imageUrl accepts Picorn storage or Dropbox/Drive share links and that imageBase64 is the alternative. The 'preview' boolean is never explained, though the mention of an inline preview implies its role; prompt length/format is left to the schema.

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

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

States a specific verb and resource ('Edit an existing picture') and then enumerates the concrete edit operations (retouch, change background, add/remove objects, restyle). The word 'existing' plus the underlying model name cleanly separates it from the sibling picorn_generate_image for creating new images.

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 implies the context of use (editing rather than generating) and states the precondition of a connected Picorn account with credits, but it never explicitly says when to pick this over picorn_generate_image or picorn_editor_* tools. No when-not guidance or named alternatives.

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 readOnlyHint=false and openWorldHint=true; the description is consistent (a write). It adds real behavioral context beyond annotations: the operation returns the changed slide as an inline preview automatically, it does not create or render video, and coordinates are the layer CENTER in canvas pixels. That is meaningful disclosure for a mutation tool.

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 ('Add a native editor layer') then layers in usage, coordinate semantics, accepted fields, and return behavior. The long comma-separated field list is dense but informational rather than wasteful; the closing 'Does not create or render video' earns its place as a scope boundary.

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 nested-object tool with no output schema, the description covers what matters: return value (inline slide preview), coordinate system, supported layer types, and the full field surface. It is close to complete, missing only per-parameter detail on the two id fields and any permission/auth notes.

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% and the nested layer object is the crux, yet the description compensates well: it enumerates the accepted persisted field families (transforms, opacity, blendMode, text/image/shape/QR styling) and clarifies that position is the layer center in pixels. projectId/slideId remain undocumented, which is acceptable given they are self-evident identifiers.

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: 'Add a native editor layer.' It maps content types (text/image/shape/group/qr) and clarifies the SVG case (image layer with isSvg:true). It is clearly a distinct create operation, though it does not explicitly contrast with siblings like update_layer or duplicate_layer.

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?

Provides concrete usage guidance: which layer types to use for static designs ('Use text, image, shape, group and qr layers') and the SVG special case. No explicit when-not-to-use or alternative-tool routing against the many editor siblings, so it falls short of the top band.

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

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

The description adds behavioral context beyond the annotations by stating the 20-slide limit and that the new slide is returned as an inline preview. However, it does not describe what happens when the limit is reached, whether existing slides are affected, or any error conditions. Since annotations only indicate readOnlyHint=false, the description provides adequate but not rich 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?

The description is two sentences long, front-loaded with the primary action, and contains no filler. Every sentence adds value: one states the action and resource, the other states the limit and return format. This is appropriately concise and well-structured.

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 a nested `background` object, three parameters, and no output schema, the description is incomplete. It does not explain the semantics of `role` or `background`, nor does it clarify how to interpret the returned inline preview or handle edge cases. The description establishes basic purpose but leaves significant gaps for an agent to invoke the tool correctly with full parameters.

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 schema has zero description coverage and the description does not explain the `role` or `background` parameters. While `projectId` is implicitly clear from the phrase 'editor project', the purpose and structure of the optional parameters remain unexplained, leaving the agent without sufficient guidance for complex inputs.

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 function with a specific verb and resource: 'Add another slide to an editor project.' It also distinguishes itself from sibling tools like picorn_editor_update_slide and picorn_editor_delete_slide by focusing on addition, and mentions the key constraint of up to 20 slides.

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 clear context for when to use the tool: whenever another slide needs to be added to an editor project, with the caveat that projects support up to 20 slides. It does not explicitly name alternative tools or exclusions, but the purpose is distinct enough that no conflicting alternative is evident.

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 annotations providing readOnlyHint=false and openWorldHint=false, the agent knows this is a mutation within a closed world. However, the description adds no further behavioral context beyond what 'align' suggests. It does not explain how alignment is computed (e.g., which layer is the reference, how 'shared bound' is determined), nor does it disclose any side effects. The description essentially reiterates the purpose without enriching the behavioral profile.

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 sentence that leads with the action verb and includes all necessary information without any fluff. It is appropriately sized and front-loaded, making efficient use of 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?

For a simple alignment tool with no output schema and minimal annotations, the description is brief but leaves some ambiguity. It does not explain what 'shared bound' means in practice (e.g., based on selection order or a collective boundary), nor does it mention prerequisites for 'positioned layers.' The tool has only four parameters, so the description is arguably adequate but not fully complete given the lack of output schema and sparse annotations.

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 does clarify the 'mode' parameter by listing the enum values ('left, center, right, top, middle, or bottom bound') and implies that 'objectIds' refer to layers. However, it does not explain 'projectId' and 'slideId' beyond their obvious context, and it does not clarify the requirement of at least two objects. This is partial compensation, not complete.

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 function with a specific verb ('Align') and resource ('positioned layers'), and enumerates the alignment modes. It distinguishes itself from sibling tools like 'distribute_layers' and 'reorder_layers' by focusing on aligning to shared bounds rather than distributing spacing or changing z-order.

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

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

The description implies when to use the tool (when you want to align layers to a common edge or center), but it does not explicitly mention alternatives or provide exclusion criteria. There is no reference to sibling tools or 'when not to use' guidance, so it only meets the 'implied usage' level.

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 readOnlyHint=false and openWorldHint=true, so the description usefully adds that engines run in the background, generated assets are stored, the SVG is converted into editable native layers, and everything is returned in one call. It also flags a non-obvious caller obligation (the editorUrl must be included in the final answer). No timing, quota, or failure behavior is disclosed, but the operational picture is substantially richer than the annotations alone.

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?

Four sentences, front-loaded with the core action and followed by the mode selection, the internal behavior, and the return contract. Each sentence carries information, though the engine/asset-storage sentence could be trimmed slightly without loss.

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 10-parameter, zero-required, nested-object tool with no output schema, the description compensates well by naming the return values (projectId, slideId, canvas dimensions, editorUrl). The main omission is that background and aspectRatio/custom-canvas interplay remain only partially explained.

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%, so the baseline is 3, and the description adds real value on top: the clipart placeholder contract for svg, the omit-svg case, the pairing of campaignId with ideaId, and the fact that width/height are only needed for custom canvases. It never explains the relationship between aspectRatio='custom' and those explicit dimensions, which is the one gap.

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

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

The description states a specific verb and resource ('Create a persistent native Picorn editor project') and then explains the two operating modes (svg-driven conversion vs. empty slide), which cleanly distinguishes it from siblings like picorn_editor_add_slide, picorn_editor_create_slideshow, and picorn_projects_create. An agent can tell what this tool does 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?

It gives a clear conditional rule: pass svg for a finished static layout, omit it only when an intentionally empty slide is wanted for incremental layer work. It also notes campaignId requires a Picorn access token and must be passed with ideaId. It does not, however, route the agent among the other project-creation siblings (picorn_projects_create, picorn_blueprint_create_file), leaving that comparison implicit.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true): declares hard bounds (50,000,000 canvas pixels, 1,000 layers), cost model (one unit per four slides, rounded up), return payload (render URLs, inline contact sheet, editorUrl), and provenance fields (modelProvider, externalLlmCalls=0). This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the core action, limits, and cost, then the return contract. Dense but nearly every sentence carries information; only the provenance sentence is arguably redundant with the cost/limit details.

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 15-parameter, nested-body, no-output-schema tool, the description adequately covers limits and return values but leaves most input parameters undescribed. An agent knows what it gets back and the guardrails, but not how to fill the majority of fields.

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 20% schema description coverage across 15 parameters, the description must compensate, but it only touches SVG constraints, layer ordering, and the ideaId/campaignId pairing that the schema already documents. Width, height, format, quality, tags, aspectRatio, transparentBackground, and the workspace keys get no added meaning.

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 (create, persist, render) plus resource (complete 1–20 slide Picorn file) and a distinguishing trait ('one deterministic call'). An agent can separate this from picorn_editor_add_slide or picorn_editor_render_project without opening schemas.

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

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

The description clarifies that agent-authored content is expected and that no LLM path is invoked, which implies when this tool is appropriate, but it never names an alternative (e.g. incremental add_slide editing, or projects_create) or states an explicit when-not condition.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context about the side effect of cleaning group references, which goes beyond the annotations' simple destructive flag.

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, front-loaded sentence that is concise and direct. It states the action and a key side effect without unnecessary 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?

The tool is a simple destructive operation with three required ID parameters. The annotations cover the destructive nature, but the description lacks explanation of parameter usage and any preconditions. It is minimally adequate but leaves gaps in parameter understanding.

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% description coverage, and the description does not explain the purpose of projectId, slideId, or objectIds. The phrase 'one or more layers' hints at objectIds but does not explicitly map to it, and no other parameter semantics are provided.

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 ('Delete') and the resource ('layers'), and adds scope ('one or more') plus a specific side effect ('clean their group references'). This distinguishes it from sibling tools like delete_slide and update_layer.

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 is provided about when to use this tool versus alternatives, no exclusions, and no mention of alternatives. The usage is only implicitly inferred from the tool name 'delete_layers'.

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?

While annotations already flag this as destructive and non-read-only, the description adds beyond that by disclosing the cascade behavior (deletes layers) and the invariant that a project must keep at least one slide. This gives the agent important context about side effects and constraints.

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

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

The description is two sentences, front-loaded with the action, and every sentence earns its place. It is appropriately concise without unnecessary 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?

For a simple deletion tool with robust annotations and a minimal schema, the description covers the key behavioral aspects: what is deleted, the cascade to layers, and the invariant. Minor omissions like return values or failure handling are not critical for this tool's complexity.

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, but it does not explain the parameters at all. The parameter names (slideId, projectId) are self-explanatory, but the description does not state which project or slide must be provided or any additional meaning beyond the schema's basic type and required flag.

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

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

The description uses a specific verb ('Delete') and resource ('a slide and its layers'), clearly distinguishing it from sibling tools like 'delete_layers' and 'add_slide'. It also provides a useful constraint about the project always retaining at least one slide, which adds clarity.

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

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

The description implies the tool is for removing entire slides along with their layers, but it does not explicitly contrast with alternatives such as 'picorn_editor_delete_layers' for removing only individual layers. The usage context is clear but lacks explicit when-to-use or when-not-to-use 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 indicate this is a mutating operation (readOnlyHint=false). The description adds that layers must already be positioned and that three or more are needed, but it does not mention reversibility, effect on unselected layers, or return value. It provides some context beyond annotations but not substantial detail.

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, concise sentence that is front-loaded with the core action. No unnecessary words or repetition of schema details.

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 distribution operation with four parameters and no output schema, the description covers the essential purpose but omits prerequisites (e.g., layers must be within the same slide/project), side effects, and return behavior. It is adequate but leaves notable gaps given the schema's low coverage.

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 clarify parameters. It explains 'horizontal or vertical' for axis and implies 'layers' for objectIds (three or more). However, it does not address projectId or slideId, leaving key context undocumented. Minimal compensation for the schema 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 clearly states the tool's function: evenly distributing layers horizontally or vertically. It uses a specific verb ('distribute'), resource ('layers'), and scope ('three or more', 'horizontal or vertical'), distinguishing it from sibling tools like alignment.

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

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

The description implies usage for distribution of three or more positioned layers, but it does not explicitly contrast with alternatives like align_layers or state when not to use the tool. The condition 'three or more positioned layers' is a partial guideline but lacks exclusion or alternative references.

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 indicate readOnlyHint=false, so the description must clarify the mutating behavior. It adds that 'all style, filter, effect, mask, and animation properties' are copied, which is useful. However, it does not mention side effects such as whether the original is unchanged, how the new layer is positioned (offset semantics), or any naming/ordering implications. This leaves some behavioral ambiguity.

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 sentence that front-loads the action and scope. Every word contributes value; there is no redundancy or filler. It is appropriately concise for a relatively simple operation.

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

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

The tool has 5 parameters, no output schema, and only minimal annotations. The description explains the core action and copy scope but omits how offsets affect the result, error conditions (e.g., trying to duplicate a group), and the outcome (new layer ID, placement). This makes the description incomplete for an agent to invoke the tool without guessing.

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 for parameter meanings. It does not. The schema has 5 parameters, including offsetX and offsetY, but the description gives no hint about what offsets do or their relation to the duplicate. The sole 'including all properties' does not address positioning or the role of the required IDs. Parameter names help, but not enough to clarify semantics.

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: 'Duplicate a non-group layer...' The verb 'duplicate' and resource 'layer' are specific, and the qualifier 'non-group layer' distinguishes this from group-related operations. It also enumerates what is copied (style, filter, effect, mask, animation properties), making the intent precise.

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 defines when to use this tool: for duplicating a non-group layer. It excludes group layers, which is a useful usage constraint. However, it does not explicitly mention alternative tools for group duplication or provide additional 'when not to use' guidance beyond the non-group condition.

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

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

Annotations only provide readOnlyHint=false and openWorldHint=false. The description adds meaningful behavioral detail by disclosing that grouping preserves world positions and render output and creates the same metadata group as the editor. This goes beyond the structured annotations and is consistent with the non-read-only nature of the 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?

The description is two concise sentences, front-loading the core purpose and adding one key behavioral detail in the second sentence. Every word earns its place with no fluff or repetition.

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

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

The description covers the core purpose and an important preservation detail, but with no output schema and zero parameter coverage, it should also mention the expected return value or group semantics. It is adequate for a simple grouping operation but leaves gaps around parameter meaning and result behavior.

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 does not explain any of the four parameters (projectId, slideId, objectIds, name). It does not clarify what objectIds are grouped or how the optional name parameter behaves, leaving all parameter meaning to the raw 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 uses a specific verb ('Create') and identifies a clear resource: 'the same metadata group used by the visual editor'. This distinguishes it from sibling tools like ungroup_layers and other layer operations, making the tool's purpose immediately clear.

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 context that the group matches the visual editor's format and preserves world positions and render output, which guides when to use it. It does not explicitly name alternatives or exclusions, but the compatibility framing implies usage for parity with the visual editor.

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 and openWorldHint=false; the description adds real behavioral context beyond that: EXIF rotation, 4096 px downscaling, JPEG-for-opaque / PNG-for-transparent storage, the 50 MB and 15 MB caps, and that without a token the asset does not land in a user-owned workspace. There is mild tension with openWorldHint=false given that arbitrary Dropbox/Drive/GCS/fal/Wikimedia URLs are fetched, though the write target remains a closed Picorn store, so it is not a clear contradiction.

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

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

Purpose is front-loaded in the first clause and every later sentence carries a distinct fact (sources, limits, transform behavior, auth effect). The single dense paragraph of long semicolon-chained sentences is slightly heavy for scanning but contains no filler.

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

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

For a 7-parameter mutation with no output schema, it covers the return contract (imageUrl for later layers), all three ingestion modes with limits, storage/transform side effects, and the auth-dependent destination. It leaves workspaceProjectId/workspaceProjectKey, the preview flag, and failure behavior 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 coverage is 71% and the schema descriptions are mostly one-liners, so the description carries extra load for the three mutually exclusive source parameters it names by field (mediaId, imageUrl, imageBase64) plus their size limits and link-handling behavior. It says nothing about name, preview, workspaceProjectId, or workspaceProjectKey, which is the residual 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 and resource ("Import a photo into Picorn storage") plus the payoff ("use the returned imageUrl in one or more native image layers"), which cleanly separates it from siblings like picorn_generate_image, picorn_design_image, and picorn_editor_add_layer. The three ingestion paths are enumerated, so an agent knows exactly what this tool accepts.

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 per-source conditions (mediaId requires an access token and comes from picorn_media_list; share links work when shared "anyone with the link"; base64 has a 15 MB cap) and a stated preference ("Prefer mediaId or a share link over base64 for full-size photos"). It never states when to choose this tool over a generation sibling such as picorn_generate_image or picorn_video_import_media, so it stops short of full routing guidance.

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

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

Annotations already establish readOnlyHint=true, so the description's 'Read' is consistent but not adding much beyond that. It does add value by specifying the included data (slides, layers, properties, z-index, image URL), but it does not describe return format, pagination, or potential size, leaving the behavioral profile only partially transparent.

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, front-loaded sentence that conveys the essential purpose and specific contents. Every word contributes 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?

For a tool with one obvious parameter and a readOnlyHint annotation, the description is largely complete. It lists the returned data elements, which is helpful given no output schema. It doesn't cover edge cases like missing project or unsaved changes, but these are not critical for a basic inspect operation.

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 does not mention projectId or its semantics at all. While the parameter name is self-explanatory, the description fails to compensate for the low schema coverage, providing no additional meaning beyond the schema's basic type and required flag.

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

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

The description uses a specific verb ('Read') and resource ('complete project'), and enumerates exactly what is included (slides, layers, properties, z-index, image URL). This clearly distinguishes it from sibling mutation tools like add/update/delete layers.

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 clearly implies the tool is for obtaining the full project state, which is sufficient context for when to use it. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations only provide readOnlyHint=false (suggesting mutation) and openWorldHint=true. The description adds significant behavioral context: it explains that static renders exclude video/audio timing, that DOCX is page-faithful, and that editorUrl is canonical. It does not explicitly state the output is URL-only or HTTP operations, but it adds context beyond the annotations, e.g., 'persistent public image URLs' implying long-term storage.

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 compact paragraph of three sentences, front-loading the action verb 'Render' and key outputs. It has minimal waste, but the enterprise wording 'page-faithful DOCX download' and 'static renders include...' is slightly dense but efficient. It is appropriately sized for the tool complexity.

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 no output schema and 7 parameters, the description covers usage intent well, including the required editorUrl. However, it fails to document critical parameter interactions (e.g., transparentBackground only works for PNG, quality ranges, page dimensions) and doesn't state any error conditions or output structure. For an agent to call it correctly, it needs more parameter guidance, but it covers the main decision points (format, slide selection, and output URLs).

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?

Schemas cover 0% of parameters, so the description must compensate. It mentions format options (png/jpeg/pdf/docx) and slide selection implicitly, but does not clarify ambiguous parameters like quality (range semantics), transparentBackground (which formats support?), or pageWidthMm/pageHeightMm (only for PDF?). It adds minimal value beyond what the schema already conveys (e.g., format enum values), but fails to elaborate on the meaning of quality and page dimensions.

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 renders slides through Picorn's Fabric editor pipeline isolants and explains what is returned (URLs, PDF, DOCX, creationUrl, editorUrl). It distinguishes itself from the sibling picorn_video_render_project by contrasting static vs video timing rendering. This gives an agent specific verb+resource with clear output enumeration.

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 directs the agent to give the canonical editorUrl to the user ('must be given to the user'), and explains when DOCX is page-faithful, plus it tells agents to use SEEZ Editor for text/layer editing. It implies the tool is for static output vs video editor for timing, distinguishing from picorn_video_render_project. This is actionable guidance for selection.

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

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

The annotations indicate readOnlyHint=false, and the description adds non-obvious behavioral detail: omitted IDs are not removed but instead preserve their relative order on top. This is critical for an agent to understand the tool's partial reordering behavior, going beyond the basic write-operation hint.

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 sentences, no filler, and immediately states the action. The key semantic detail about omitted IDs is packed into one clear sentence. It is efficiently front-loaded and easy to parse.

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 layer-reordering tool, the description fully covers the necessary behavioral nuances: the ordering convention and the handling of omitted IDs. The mutation context is provided by annotations, and no output schema is needed. An agent can confidently invoke this tool without further clarification.

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 0% schema description coverage, the description compensates by explaining the key parameter objectIds ('bottom-to-top'). However, projectId and slideId are not elaborated beyond their names, relying on obvious context. The essential ordering parameter is well covered, but the other two 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?

The description opens with a specific and unambiguous verb+resource: 'Set layer order.' It clearly distinguishes this tool from siblings like add_layer or delete_layers by focusing exclusively on reordering. The added detail that objectIds are 'bottom-to-top' precisely defines the intended operation.

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 explains how to use the tool by defining the order semantics and the behavior for omitted IDs ('retain their relative order on top'). This gives clear context for when to use it, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=false, so the mutation nature is known. The description adds the key behavioral trait that child layers are preserved, which is critical for understanding the operation's effect. However, it does not explain side effects like re-parenting or nested group 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 a single, direct sentence with no filler. It states the action and outcome efficiently, earning its place without unnecessary detail.

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 operation, the description captures the core effect. However, it leaves open questions about return values, whether groupId must reference an existing group, and how child layers are re-parented. With no output schema and sparse annotations, a bit more detail would improve 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?

The schema has 3 required string parameters with no descriptions (0% coverage). The description does not mention any parameters or explain how projectId, slideId, and groupId relate to the operation. With low schema coverage, the description fails to compensate, leaving parameter semantics under-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?

The description uses the specific verb 'Remove' with the resource 'group' and clarifies the outcome 'preserving all child layers'. This clearly distinguishes it from sibling tools like delete_layers (likely removes children) and group_layers (creates a group).

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

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

The description implies the use case (removing a group while keeping children) but does not explicitly name alternatives or state when not to use it. There is no mention of how it contrasts with delete_layers or the need for a valid existing group.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=false, so the agent infers this is a write operation. The description adds the return behavior ('Returns the changed slide as an inline preview automatically') and enumerates what can be patched. However, it does not explain whether the patch merges or overwrites layer properties, which is important for predicting side effects.

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 two sentences, front-loaded with the action and then the return value. The list of properties is long but informative and not wasteful. There is no redundancy or 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?

Despite listing many patchable properties, the description omits key contextual details: the 'commitType' parameter is undocumented, the structure of the nested 'patch' object is unspecified, and there is no output schema to clarify the preview format. For a tool with this complexity, the description is incomplete for reliable invocation.

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

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

Schema description coverage is 0%, so the description is the only source for parameter semantics. Although it lists editable property categories, it does not provide the exact key names or value structures expected inside the 'patch' object, nor does it explain the 'commitType' enum. This is insufficient for correctly constructing a patch call.

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

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

The description uses a specific verb ('Patch') and names the resource ('a layer') with a comprehensive list of editable properties, including content, position, size, and more. This clearly distinguishes it from sibling tools like update_slide for slide-level changes and gives the agent a precise understanding of the tool's scope.

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 clearly implies when to use this tool: whenever you need to modify any property of a specific layer. However, it does not explicitly state when not to use it or mention alternatives like update_slide for slide properties, so it stops short of full exclusion 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 indicate this is a mutating operation (readOnlyHint false). The description adds that it 'returns the changed slide as an inline preview,' which is useful behavioral context beyond the annotation. No contradictions with 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?

The description is a single concise sentence with no redundant wording. It front-loads the action and scope, making it easy for an agent to parse quickly.

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 five parameters (including a nested object), no output schema, and sparse annotations, the description gives a high-level purpose and return behavior but lacks details on parameter formats, constraints, or how to construct the background object. It is adequate for a simple update tool but leaves gaps for full invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does map 'background,' 'semantic role,' and 'image prompt' to the role/background/imagePrompt parameters, but it omits explanation of required projectId/slideId and the background object's nested structure. Thus partial compensation.

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 function: 'Change a slide background, semantic role, or image prompt.' The verb 'change' and the specific slide attributes distinguish it from siblings like add_slide, delete_slide, and update_layer.

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

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

Usage is implied by the description—it is the tool for modifying slide background/role/prompt—but there is no explicit when-to-use guidance or mention of alternatives among the many sibling tools. The context is clear enough for basic selection, but no exclusions 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=true and openWorldHint=false, and the description adds real value beyond them: the access-token requirement, newest-first ordering, nextCursor pagination, the semantics of web-editor files (posts the last rendered slides), and the mcpEditable flag. It does not cover rate limits or result-size caveats.

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

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

Front-loads the core purpose and return fields before the integration notes. It is dense but every sentence carries distinct information (fields, auth, scheduling, editability, pagination); slightly run-on in the middle clauses.

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

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

With no output schema, the description compensates by listing returned fields, and it also covers auth requirements, ordering, and pagination. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema (limit default 20, cursor = nextCursor from previous page). The description's 'Page with nextCursor' merely restates the cursor schema rather than adding syntax or limits, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the user's own Picorn files'), scopes it to posts and slideshows, and enumerates the exact fields returned (fileId, title, project, aspect ratio, thumbnail, editorUrl) plus sort order. An agent can tell this apart from picorn_posts_list and picorn_media_list from the text alone.

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

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

Explains what the results enable downstream: any fileId can be fed to picorn_posts_schedule, and files with mcpEditable: true can be modified via picorn_editor_* tools. It also clarifies no workspace key is required. It stops short of naming an explicit alternative or when-not-to-use condition.

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

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

With only readOnlyHint=false and openWorldHint=true available, the description adds substantial unstated behavior: it requires a connected Picorn account with credits, is billed at 1.2x the fal price, gives a concrete cost anchor (~1 ct for ~1 MP), and names the return payload (inline preview, public imageUrl, chargedCents). That is exactly the billable/external-dependency context 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?

One dense paragraph that is correctly front-loaded: purpose, then mode selection, then the library-first rule, then cost/return. It is efficient with no filler, though the run-on construction of the middle 'kind' clauses slightly slows parsing.

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, and the description compensates by naming the returned fields (preview, imageUrl, chargedCents). Auth and billing prerequisites are covered too. The remaining gap is that half the geometry/pagination-style parameters receive no behavioral explanation, which is a minor omission for a straightforward generation call.

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 33%, so the description must compensate. It does clarify 'kind' well (default photo maps to Krea 2 Turbo, text maps to GPT Image 2.5 Flare for lettering-heavy mockups) and implies prompt content and cost scaling with resolution, but width, height, aspectRatio and preview are left entirely to the schema — three of six parameters get no added meaning.

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 ('Generate a new picture on fal') and immediately distinguishes the two modes with the underlying models (Krea 2 Turbo vs. GPT Image 2.5 Flare). An agent can separate this from picorn_edit_image, picorn_design_image and picorn_generate_vector_assets 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 prescribes 'Library first' with the alternative tool named (picorn_search_library, or search lines in picorn_blueprint_compile) and gives the when-not condition: generate only when no fitting hero photo exists and the design would benefit massively. This is a full routing rule, not an implied one.

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 only readOnlyHint=false and openWorldHint=true in annotations, the description carries the burden of explaining behavior. It clearly discloses the multi-step process, the five-variant generation, the selection of the top three, and the extra layered editor file for signets. It does not mention timing, side effects, or failure modes, but the core operational behavior is well disclosed.

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

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

The description is three sentences with no filler, front-loading the core purpose and workflow. Every sentence adds meaningful context: the pipeline, the variant/output behavior, and the signet-specific return value.

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

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

The description explains the output behavior well given no output schema, notably the top-three return and signet layered file. However, it does not explain the optional parameters or the workspace context needed to invoke the tool fully, and it gives no guidance on failure or error behavior. It is adequate for selection but not fully complete for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters, but it only vaguely references 'signets or icons' and 'multi-colour SVG converter.' It does not clarify prompt, palette, numColors, projectName, or the workspace identifiers, leaving the agent to infer most parameter meanings from names and schema constraints alone.

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

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

The description names a specific verb and resource ('generate native vector signets or icons') and details the full pipeline from raster generation through background removal to SVG conversion. It also distinguishes this tool from sibling image/editor tools by stating it is for signets and custom icons, not general editing or raster generation.

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 final sentence, 'Use this tool for every newly generated signet and custom icon,' gives explicit context for when to invoke this tool. It does not list exclusions or explicitly compare against sibling tools like picorn_design_image or picorn_generate_image, but the 'every newly generated' phrasing sufficiently signals the intended 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?

With readOnlyHint=true and openWorldHint=false already declaring the safety profile, the description adds real behavioral context: newest-first ordering, cursor-based paging ('Page with nextCursor'), the auth requirement ('Requires a Picorn access token'), and what includeGenerated changes. It stops short of describing limits or failure behavior, so it is strong but not exhaustive.

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?

Four tightly-packed sentences, each carrying distinct information: what it lists, what it returns, how to use the result, optional-generation flag, paging, and auth. The purpose is front-loaded and no sentence is filler.

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

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

With no output schema, the description usefully enumerates retrieved fields (mediaId, imageUrl, thumbnailUrl, pixel size), and it covers paging and auth. Given three simple parameters and a read-only list operation, it is nearly complete; only edge cases like empty results or rate limits are unaddressed.

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 67% and includeGenerated has no schema description at all; the description compensates by explaining 'includeGenerated: true also lists images Picorn generated for the user' and by explaining how cursor pairs with 'nextCursor'. That goes beyond the schema for the weakest-documented parameter, though limit/paging defaults still live mainly 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 gives a specific verb and resource ('List the photos the user already uploaded to Picorn') plus scope (newest first), so the agent knows exactly what it does. It does not, however, differentiate itself from the similarly-named sibling picorn_files_list, leaving a small ambiguity about which listing tool to pick.

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

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

It states the motivating use case ('so a post can be built from them without uploading again') and names concrete downstream routes ('Pass a mediaId to picorn_editor_import_image, or use the imageUrl directly in an image layer'). That is clear context for when to reach for it, though it never says when a different list tool would be preferable.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value with the concrete outcome ('removed from the social media scheduler') and the auth requirement ('requires a Picorn access token'), which annotations do not convey.

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

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

Two tight clauses with the core outcome front-loaded and the auth prerequisite appended. No wasted language, though the auth note could be folded more naturally.

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 cancel tool whose annotations already cover the destructive/open-world profile and with no output schema, the description covers outcome and auth adequately. The only real gap is that fileId semantics remain undocumented in both schema and description.

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 fileId parameter, so the schema provides no semantics. The description only implies that the fileId identifies 'a file' but adds no format, source, or retrieval guidance to compensate for the gap.

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

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

The description states a specific verb and resource: cancel the scheduled post of a file, clarifying that it is removed from the social media scheduler. This clearly distinguishes the inverse of picorn_posts_schedule, though it never names that sibling explicitly.

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

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

It gives a timing condition ('before it is published'), which implies when the tool applies. However, it offers no explicit when-not guidance, alternatives, or error conditions (e.g., what happens if the post is already published).

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 and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the access-token requirement. It does not disclose pagination behavior or what the limit does to results, which is the notable remaining gap.

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

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

Two compact sentences, front-loaded with the core action and scope, with the prerequisite placed at the end. Nothing is wasted, though it is a touch thin for a three-parameter list tool.

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 burden of explaining the return shape, but says nothing about ordering, pagination, or the response structure. It covers the input format adequately for an agent to make a call, but leaves meaningful ambiguity about results.

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 all three parameters (to, from, limit). The description only clarifies that from/to are ISO dates; it says nothing about which bound means what, whether they are inclusive, or what limit controls and its 1–200 bounds (which are in the schema but unexplained). It compensates for only part of a substantial 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 (scheduled and published posts) with a scope qualifier (time window) and format hint (ISO dates). It distinguishes itself well from picorn_posts_schedule and picorn_posts_cancel, though it doesn't name them, which keeps it just short of a 5.

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

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

Usage is implied by the name and scope but never spelled out — no statement of when to prefer this over picorn_campaigns_list or how it relates to the schedule/cancel siblings. An agent can infer intent but gets no explicit 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 non-read-only, open-world, non-destructive, but the description adds substantial behavior beyond them: per-post cost ($0.02 from balance), idempotent reschedule on repeat calls for the same file, re-render vs original-bytes publishing semantics, per-platform account fallback logic, and the access-token requirement. It does not disclose partial-failure behavior when one platform fails, which keeps it from a 5.

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

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

Purpose and source options are front-loaded, then semantics, then constraints and cost. Every sentence carries actionable information (pricing, idempotency, auth, format). It is dense and long, but no clause is pure filler.

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

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

For a mutation tool with 8 parameters, 50% schema coverage, and no output schema, the description supplies the missing operational context: auth, cost, idempotency, scheduling format, and account selection. The main gap is failure/error semantics (what happens if scheduling partially fails across platforms or the token lacks scope), which an agent invoking a paid, multi-platform mutation would benefit from.

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 50%, so the description must compensate and largely does: scheduledAt format and a concrete ISO-8601-with-timezone example, publishNow: true meaning immediate post, accountIds source plus the 'each must be on one of the platforms' constraint, and the render true/false consequence (re-render vs original bytes). fileId and platformConfigurations are left to the schema. Clear value added over structured fields.

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 (schedule a finished static Picorn file or an existing video) and immediately distinguishes the two accepted sources, explicitly naming picorn_posts_upload_video for videos. An agent can tell this apart from picorn_posts_list, picorn_posts_cancel, and picorn_render_svg 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?

States when to use it (finished static file or existing uploaded video) and routes to alternatives: accountIds must come from picorn_account_status, video must come from picorn_posts_upload_video, and ownership is verified via picorn_files_list. Also distinguishes scheduling from immediate publishing via publishNow. Explicit when/where conditions throughout.

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 annotations (readOnly=false, destructive=false), it discloses the 15 MB decoded size cap, the return contract (fileId, mediaUrl, published:false), the fact that upload alone does not publish or incur a posting charge, and that account access is required. This is rich behavioral context the annotations alone do not carry.

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

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

Front-loaded with the core action and constraints, and nearly every sentence carries distinct information (scope, size cap, return values, next step). It is dense but not padded; slightly long, though no sentence is wasted.

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

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

With no output schema and 0% param coverage, the description still covers the action, input constraints, required auth, return values and the follow-on publish step. An agent has everything needed to invoke it correctly and chain it into picorn_posts_schedule.

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 compensate; it clarifies that mediaBase64 must be raw bytes (not a URL) with a 15 MB decoded limit, and that contentType accepts MP4/WebM/MOV, matching the enum. The caption parameter is left undocumented, so it falls short of full compensation.

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 ('Upload an existing MP4, WebM or MOV clip') and immediately scopes it against the neighboring capabilities by excluding generation, editing and rendering. An agent can distinguish this from picorn_generate_image or the editor tools 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 explicit when-to-use guidance ('Download a licensed source clip in your client first; a webpage URL is not video bytes'), the exclusion set (no generation/editing/rendering), and the named next-step alternative picorn_posts_schedule with the exact parameters needed. Nothing about routing is left to inference.

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

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

The description is consistent with the annotations: readOnlyHint=false aligns with the create/write behavior. It adds useful context beyond the annotations by noting that the project holds editor files and imported assets and that the returned workspaceProjectId and workspaceProjectKey must be preserved together for later operations. It does not elaborate on openWorldHint implications such as possible additional side effects, but the create semantics and annotations cover the core 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 two sentences with no filler: the first states the primary purpose and the second gives the critical operational instruction about returned IDs. It is well-structured and 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?

With no output schema, mentioning the returned workspaceProjectId and workspaceProjectKey is valuable and necessary. However, the description omits parameter semantics and does not explicitly differentiate this tool from the sibling project-creation tools, leaving meaningful gaps given the 0% schema description coverage and openWorldHint.

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 does not mention or explain any of the three parameters: name, brandColors, or description. The agent must infer parameter meaning solely from raw JSON schema, which is especially insufficient for brandColors and its nested structure.

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

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

The description uses a specific verb ('Create') and resource ('marketing project') and adds a clear capability: it can hold many editor files and imported image assets. This distinguishes it from sibling project-creation tools at a high level, though it does not explicitly name the alternatives.

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

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

The description implies a use case: creating a marketing project to contain editor files and imported assets, and it gives a follow-up instruction to keep the returned IDs for related operations. However, it does not explicitly say when to choose this tool over picorn_editor_create_project or picorn_video_create_project, nor does it provide when-not-to-use 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, and the description aligns with that by listing read-only items (files, assets, brand profile). It adds context beyond annotations by specifying the included fields (thumbnail, status, creation URL, editorUrl) and instructs the agent to always surface editorUrl, which is useful behavioral guidance.

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, each earning its place: the first states the core action and scope, the second details what file entries include, and the third gives a clear user-facing directive. It is front-loaded with the action and contains no filler.

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

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

For a read-only inspection tool with no output schema, the description covers the main return contents (files, assets, brand profile, and specific fields) and provides the instruction about editorUrl. It does not explain the meaning of 'status' or the structure of the response, but given the annotations and the nature of the tool, it is reasonably complete.

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 schema lists two required parameters (workspaceProjectId, workspaceProjectKey) with 0% description coverage. The tool description does not explain their meaning or format, leaving the agent without clues about how to fill them. This is a critical gap for a tool with required params.

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

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

The description uses a specific verb 'List' and clearly identifies the resource: every editor file, imported asset, and the project brand profile. This distinguishes it from other project tools like picorn_editor_inspect_project by the detailed scope of what is listed.

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

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

The description implies this tool is for inspecting a marketing project's contents, and the instruction 'Always give the user that editorUrl' provides a usage directive. However, it does not explicitly state when to prefer this tool over the similar picorn_editor_inspect_project or any other alternatives.

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

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

The annotation readOnlyHint=false already signals mutation, and the description reinforces this with 'Update' while adding useful behavioral context: it returns 'its complete file, asset, and brand index'. This goes beyond the structured annotations, though it does not detail side effects or failure modes.

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

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

The description is a single well-structured sentence, front-loaded with the action ('Update'), followed by the update targets and the promised return value. There is no filler or redundant wording.

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, no parameter descriptions, and only readOnlyHint=false, the description carries most of the burden. It gives a high-level purpose and return value but fails to explain required identifiers, brand color item format, or partial-update behavior, leaving the agent without enough information to construct a correct call.

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 mentions three updatable fields (name, description, brandColors) but omits the required workspaceProjectId and workspaceProjectKey, and does not explain the structure of brandColors items. This is insufficient for reliable invocation.

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

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

The description uses a specific verb ('Update'), identifies the resource ('marketing project'), and lists the updatable fields ('name, description, or named color scheme'). This clearly distinguishes it from sibling tools like picorn_projects_create and picorn_projects_inspect.

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 makes the context clear: use this tool to modify an existing project's name, description, or colors. It does not explicitly name alternatives or provide exclusion criteria, but the update semantics are obvious from the verb and resource.

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 readOnlyHint=false, it discloses that Picorn resolves all placeholders internally and that the tool 'Returns an inline preview and public creationUrl,' which matters since there is no output schema. It also draws a behavioral boundary around not performing the conversion in a separate admin call.

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?

Six sentences cover purpose, mechanism, three engine options, constraints, and return value with no filler, and the purpose is front-loaded. The engine-enumeration sentence is dense, but each clause carries distinct information that 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?

The mechanism, engine options, and return shape are covered, which is substantial for a tool with no output schema and zero param descriptions. However, width, height, and preview parameters are entirely undocumented, and there is no failure behavior or worked example to anchor the declarative workflow.

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

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

With schema description coverage at 0%, the description carries full burden. It richly specifies the svg parameter (placeholder <rect> elements, data-clipart-engine/prompt/num-colors/keep-bg attributes) but says nothing about width, height, or preview beyond schema min/max constraints.

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 first clause, 'Render your SVG through Picorn with real typography and declarative image workers,' states a specific verb (render) and resource (SVG). The placeholder mechanism and engine-mode detail make it unmistakably distinct from siblings like picorn_generate_image or picorn_editor_render_project.

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

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

The description gives conditional backend-selection guidance (svg-converter for fresh ComfyUI scenes, z-image-turbo for raster cutouts, library for existing vectors) and an explicit when-not instruction: 'never call the admin converter or return generated base64 yourself.' It does not name sibling tools as alternatives, but the internal routing conditions are explicit.

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

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

The readOnlyHint annotation already declares this a safe read operation; the description adds the behavioral detail that results are 'approved' shapes, indicating a curated set. No contradictions.

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 sentence that immediately states the primary action and resource, with zero filler 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?

While the core purpose is clear, the description omits any explanation of the three parameters, the meaning of 'approved', or the output format. With no output schema, the agent is left without sufficient context to construct effective queries.

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 provides examples of shape types (torn, wavy, blob, banner) that likely map to the 'style' parameter, but gives no guidance on 'limit' or 'aspect', leaving their semantics unexplained.

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

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

The description uses a specific verb ('Find') and names the resource ('approved torn, wavy, blob, banner and other decorative shapes'), clearly distinguishing it from sibling tools like picorn_search_icons.

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

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

The description implies the tool is for retrieving decorative shapes for designs, but does not explicitly state when to use it over alternatives like picorn_search_icons, nor does it mention any exclusions or prerequisites.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the main behavioral concerns. The description adds no contradictory behavior and implies a non-mutating search, but it does not disclose additional traits such as result format, pagination, or how open-world results may vary.

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, front-loaded sentence with no filler. Every word contributes to understanding the tool's core action and context, making it highly concise and well structured.

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 search tool with one required parameter, the core action is clear, and the annotations cover safety. However, there is no output schema, and the description does not mention what results look like or how optional filters affect the search, leaving some ambiguity for an agent.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only says 'vector icon library,' which hints that query is an icon search term, but it does not explain limit, style, or visualStyle. The parameter names and enums are somewhat self-explanatory, but the description does not compensate for the lack of schema descriptions.

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

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

The description uses a specific verb and resource: 'Search Picorn's vector icon library.' This clearly distinguishes it from sibling tools like picorn_search_areas (areas) and picorn_generate_image (generation), making the tool's purpose immediately identifiable.

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 phrase 'before composing a design' clearly conveys when this tool is useful in a workflow. However, it does not explicitly state when not to use it or name alternative tools, 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.

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful non-schema context: the search is free and works without an account, and results come back as a single numbered contact sheet, which tells the agent what to expect.

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?

Dense but front-loaded, with the core routing rule first and the workflow/costing caveats after. Every sentence carries information, though the Blueprint cross-reference sentence is long and slightly packed.

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

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

With no output schema, the description correctly describes the return shape ('one numbered contact sheet') and gives ordering/mapping notes for reuse in Blueprint. It is nearly complete for a search tool, missing only clarifications for the un-described filter parameters.

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

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

Schema description coverage is 0%, so the description must carry the load. It partially does: it enumerates acceptable 'kind' values and gives real guidance for 'q' (German or English, short concrete English nouns match best). However, limit, orientation, and transparent are entirely unexplained, leaving half the parameters undocumented.

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

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

States a specific verb (browse/search) plus the resource (Picorn's own picture library) and enumerates the content kinds it covers. It clearly distinguishes itself from siblings like picorn_search_icons and picorn_generate_image by scoping to the library and naming the generative alternative explicitly.

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

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

Leads with 'LIBRARY FIRST' and states the when-not condition: generating costs credits and is 'the exception: only when nothing here fits.' It also prescribes the follow-up workflow into picorn_blueprint_compile with the exact syntax to use.

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 readOnlyHint=false and openWorldHint=true; the description adds real value on top, disclosing that it returns an authUrl, that a human must open it in a browser (interactive, out-of-band step), and that a Picorn access token is required. It does not cover link expiration or failure modes.

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

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

Two short sentences, front-loaded with the core action, each carrying distinct information (what it creates, how to use the result, what it requires). 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?

With no output schema, the description correctly explains the return (authUrl) and the required auth. It leaves minor gaps (link lifetime, error behavior), but an agent has enough to invoke it and route the next step correctly.

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

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

Schema description coverage is 0%, so the description should compensate but says nothing about the single 'platform' parameter. The parameter name plus its 8-value enum make intent self-evident, so this is minimum-viable rather than a serious 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 and resource: 'Create an OAuth link that connects a social media account to the user's Picorn account.' This clearly separates it from siblings like picorn_account_status (which it names) and the campaigns/editor 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?

Gives a concrete workflow: hand the authUrl to the user for a browser, then check picorn_account_status. This routes the agent to the right follow-up tool. It lacks explicit when-not/exclusion guidance, 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.