Posy

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

Annotations already declare this is a non-destructive, non-idempotent write, so the safety profile is covered. The description adds useful behavior with 'auto-detect' for input/inputs, but omits that repeated calls create duplicates (non-idempotent), any auth requirements, and the 30-item cap that lives in the schema.

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

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

Two sentences, front-loaded with the action and the legal argument shapes, no filler. Every clause maps to a distinct calling mode.

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 6-parameter, nested-object mutation with no output schema, the description covers the central ambiguity an agent faces (what to pass for the content). Gaps remain around size/color defaults and duplicate behavior on repeat calls, but nothing blocks a correct invocation.

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

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

With 67% schema coverage, the description's main contribution is disambiguating the mutually exclusive input paths: `inputs` for a batch, `input` for a single value, `tile` for a raw object. It doesn't touch size, color, or after, but the enums and existing schema text carry those adequately.

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 tiles') that sits clearly against the update_tile/move_tile/remove_tile siblings. It doesn't explicitly name an alternative, but the add-vs-modify distinction is unambiguous from the name and first sentence.

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 the three input modes (inputs for several, input for one, tile for full object), which is implied usage guidance for how to call it. It gives no explicit when-to-use or when-not-to-use against siblings like update_tile or import_page, so the agent must infer.

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 cover the safety profile (non-readOnly, non-destructive, non-idempotent, closed-world), so the bar is lower. The description still adds non-obvious behavior: the one-page-per-account constraint and the fact that this claims a public username, which together explain why it is not repeatable. It does not say what happens if the username is already taken.

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 short sentences, front-loaded with purpose and precondition, then the style hint and the follow-up workflow. No filler and nothing repeated from the schema.

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

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

With no output schema and a 6-param creation tool, the description covers purpose, precondition, key option, and next steps. It omits failure behavior (username collision) and what the call returns, which an agent arguably needs before chaining into add_tile.

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 the description only addresses `style` (omit for a starter template) while adding genuinely useful routing to list_options for what each look is like. Four of six parameters (layout, preset, template, empty) get no mention in the description, so it neither compensates for the coverage gap nor falls below the baseline for a partially documented 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+resource ('create the user's page') and adds a scope constraint ('one per account') plus the username-claim side effect. An agent can distinguish this from get_page, import_page, and add_tile 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?

Explicit precondition naming a sibling: 'Do this once, when get_page says there is no page.' It also routes style selection to list_options and tells the agent what to do next ('Then add tiles and publish'), covering both when-to-use and what-follows.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful non-annotated context by naming the returned fields, but it does not state any additional behavior such as error cases when no page exists or whether it reads published vs draft state beyond the word 'draft'.

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

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

A single tight sentence with no filler, though it is a fragment lacking a leading verb, which slightly reduces front-loaded clarity. Every listed element earns its place as return-content documentation.

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 no parameters, the description carries the burden of explaining what comes back, and it does enumerate the key return fields (profile, theme, tiles with ids, URL, version, unpublished-change flag). The main gap is the absence of an explicit action verb and any mention of behavior when the page does not exist.

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, which sets the baseline at 4 per the rubric. There is nothing parameter-related for the description to clarify or omit.

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 is a noun phrase enumerating the returned contents (draft, URL, version, unpublished changes) rather than stating a verb, so the retrieval intent is only inferred. It does imply scope (the current draft of a single page) which partly separates it from siblings like list_options or publish, but there is no explicit 'returns/retrieves' statement.

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

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

No guidance on when to call this versus siblings such as create_page, list_options, or publish, and no statement of prerequisites or context. The agent must infer coverage entirely from the tool name.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false and idempotentHint=false; the description adds the crucial nuance that destruction is scoped — an existing page's draft is replaced only when replace is true. It doesn't cover permission requirements or failure behavior, so it stops short of a 5.

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

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

Two tightly packed sentences, front-loaded with the operation and accepted formats, then the create-vs-replace conditions. 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 mutation tool with no output schema, the description covers inputs, creation vs. replacement conditions, and the destructive scope. Gaps remain on return values and error handling, but the essential calling contract is 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?

Schema coverage is 67% with 'file' documented as brief-or-page-JSON plus a format doc link; the description adds meaning to the two undocumented-ish params by tying username to the create path and replace to draft overwrite. It doesn't clarify what the response is, but for parameters it adds real value over 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 (load/import) and resource (whole page) plus the two accepted input formats (Posy brief with name/bio/look/theme/links[], or full page JSON). It partially distinguishes itself from the create_page sibling by describing the create-if-missing path, but never names create_page as the alternative.

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 conditional routing: pass username when there is no existing page, and replace-respecting behavior when one exists. This is clear when-to-use context, but no exclusion or named alternative (e.g., 'use create_page instead for a blank page') is provided.

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 this as a read-only, idempotent, non-destructive, closed-world operation. The description adds useful scope by naming the option categories and noting that looks include a note and palettes, but it does not describe return format or other operational details beyond those 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?

It is a single, front-loaded sentence that enumerates the covered option categories without filler. Every listed category contributes to understanding what the tool returns.

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-parameter read-only enumeration tool with annotations covering safety, the description is largely complete because it names all relevant option categories. It is slightly incomplete because it only hints at return structure for looks and does not describe how the other option categories are returned.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; this meets the baseline of 4. The description correctly does not waste space discussing 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 identifies the resource as allowed configuration values and enumerates the option categories (looks, themes, fonts, backgrounds, tile styles, sizes, colours, social platforms). It does not explicitly differentiate this lookup tool from sibling action tools such as set_theme or set_profile.

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 'Allowed values,' suggesting the tool should be called when valid option values are needed. However, it does not state when to use this versus alternatives or call out prerequisites for the setter tools that would consume these values.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context beyond that. It adds nothing about side effects such as whether other tiles shift positions, what happens with an out-of-range index, or whether moving a tile requires auth.

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

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

A single front-loaded sentence with zero filler that states action, target, and destination semantics compactly.

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 two-parameter mutation with an annotation-supplied safety profile and no output schema, the description covers the core action. However, it omits the reordering side effect on other tiles and index-boundary behavior, which matter for a positional mutation.

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 clarifies that position is 0-based in the tile list, which meaningfully interprets the integer/minimum-0 schema, but it says nothing about the 'id' parameter or out-of-range behavior.

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

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

States a specific verb and resource ('Move a tile') and adds the destination semantics ('to a 0-based position in the tile list'). The verb distinguishes it from add_tile, remove_tile, and update_tile, though it does not explicitly name an alternative sibling.

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 or when-not-to-use guidance is given. There is no hint about how this differs from update_tile, which an agent could reasonably confuse with a move/reorder operation.

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 idempotent=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact the annotations do not convey: the result becomes publicly reachable at a public URL. It says nothing about auth requirements, reversibility, or failure when no draft 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?

A single tight sentence with no filler, and the outcome (live, public URL) is front-loaded. It is arguably over-terse given the zero-parameter targeting question, but nothing is redundant.

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 and no output schema, the description carries most of the burden, and it does convey the core effect and public exposure. It omits which draft is published (the tool takes no identifier), what is returned, and error conditions, leaving real gaps for a publishing 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?

The schema declares zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. However, the absence of any targeting parameter while the description says 'the draft' leaves an unexplained implicit-context dependency.

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

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

States a concrete action and its outcome: the draft becomes live at the public URL. This is unambiguous and clearly distinct from siblings like create_page, get_page, and update_tile, though the description never names those siblings to draw the boundary 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?

There is no guidance on when to call this versus create_page or update_tile, nor on prerequisites (e.g., a draft must already exist, or which draft is affected given zero parameters). The agent must infer the trigger conditions entirely.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered by structured data. The description adds nothing beyond that — it doesn't say the deletion is permanent, whether nested content is removed, or what happens if the id is unknown. A 3 reflects a description that neither contradicts nor enriches 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?

A single six-word sentence with the verb and identifier front-loaded and zero filler. It is appropriately sized for the operation, though its terseness trades away information rather than being genuinely optimal.

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 delete with no output schema, the bare mechanics are covered and annotations carry the destructive/idempotent profile. What's missing is behavioral fallout — whether the removal is recoverable and what an invalid or already-deleted id returns.

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?

One parameter with 0% schema description coverage, so the description is the only place meaning could be added. "By id" merely restates the schema property name and gives no format, source, or validity guidance for the id value.

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 ("Delete a tile") plus the identifying key ("by id"), which cleanly separates it from add_tile, update_tile and move_tile by operation type. It stops short of naming those siblings or contrasting scope, so it's clear but lacks explicit differentiation.

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

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

There is no statement of when to use this tool versus update_tile or move_tile, and no prerequisites or conditions. The agent must infer from the verb alone that this is the terminal removal path.

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

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

Annotations already declare the tool is mutable, local, idempotent, and non-destructive. The description adds which profile fields are changed and that avatarFocus/avatarZoom affect avatar cropping, but it does not clarify partial-update semantics, permissions, or validation 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?

Two compact sentences, front-loaded with the primary fields and followed by avatar-specific details. Every phrase earns its place and there is 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?

The description identifies the updatable fields and avatar cropping behavior, which covers the core operation. However, for a six-parameter mutation tool with all-optional parameters, it omits whether omitted fields remain unchanged, validation rules, and expected response behavior, leaving meaningful 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%, so the description must compensate. It names all six parameters and explains that avatarFocus and avatarZoom crop the avatar, but the 0–100 and 1–3 ranges duplicate the schema, and field formats or partial-update semantics remain 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 states a specific verb ('Change') and lists the profile fields affected (name, bio, avatar URL, location), plus avatar cropping behavior. It is clear but does not explicitly differentiate itself from sibling tools, though none of the listed siblings are profile-related.

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 used to update profile details but provides no explicit when-to-use guidance, prerequisites, or conditions for choosing this tool over alternatives. No exclusions or context 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 non-read-only, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely useful behavior beyond that: it is a partial/patch update where omitted fields are untouched. It still says nothing about the scope of the change (account-wide vs. page-level) or permission requirements.

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

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

Three tight sentences, front-loaded with the action and the partial-update rule before the parameter notes. The parenthetical re-listing of style options mildly duplicates the schema enum, but it usefully anchors the cozy=Desk mapping.

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 14-parameter tool with a nested background object, no output schema and 7% schema coverage, the description is far too thin. It never explains how style/preset interact with the individual knobs (does preset override accent?), what the other twelve parameters do, or whether changes are global or scoped.

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 7% (just `style`), so the description must carry the load for 14 parameters and it explains only two of them (`style` and `preset`). Font, align, accent, avatar, effect, layout, motion, photos, radius, ambient, tileStyle and the entire nested `background` object are left as bare enum values with no meaning attached.

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

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

States a concrete verb ('Change') plus the resource and its parts (colours, fonts, layout, other theme settings), so an agent knows exactly what this does. It does not explicitly contrast itself with the nearest sibling set_profile, which is the only gap keeping it from a 5.

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

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

'Only pass what should change' gives the key partial-update usage rule, and it routes the agent to list_options to discover which palettes pair with which look. There is no explicit when-not-to-use guidance (e.g. versus set_profile or per-tile styling in update_tile).

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

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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=false), so the description doesn't need to restate it. It instead adds genuine behavioral context: the patch is a partial-update map of field names to values, and crop has constrained focus (0–100) and zoom (1–3) ranges. It omits error behavior and required permissions, keeping it short of a 5.

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

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

Front-loaded with the core action, then two compact example blocks that carry the format burden efficiently. No filler sentences; every clause (including the range annotations on focus and zoom) 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?

No output schema exists, and for an update tool the description covers the risky, non-obvious part — the shape and constraints of the free-form patch. Missing pieces are minor: what the id refers to and whether sibling tools are needed for other tile mutations.

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

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

Schema coverage is 0% and the patch parameter is an unconstrained object with additionalProperties, so the description is the only source of valid keys — it supplies size, title, color, text, and the nested focus/zoom structure with valid ranges. The id parameter remains unexplained, so it doesn't fully compensate for the coverage gap.

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

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

States a specific verb+resource ("Change fields of a tile") and immediately grounds it with concrete patch examples, which separates it cleanly from siblings like add_tile, move_tile, and remove_tile. An agent can tell what this 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?

Implied usage is clear (modify an existing tile's fields), and the crop example signals a second capability. However, it never names alternatives or boundaries — e.g. that positional changes belong to move_tile, or that this cannot create a tile. No explicit when/when-not guidance.

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