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

Annotations already declare non-readOnly, non-idempotent, non-destructive. The description adds genuinely useful context beyond them: the hint is persisted into a preamble and affects future sessions, which signals global scope. However, it omits that non-idempotency means repeated calls create duplicate hints, and says nothing about where or how the hint is stored or whether it requires validation.

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

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

A single tight sentence with the action front-loaded and no padding. It is efficient, though its brevity is partly the reason key usage and parameter details are missing.

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 persistent-state mutation tool with no output schema and zero schema description coverage, the description should explain verification requirements, duplicate handling, and the relationship to affinity_search_sdk_hints. None of that is present.

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% for the single required 'hint' parameter, so the description must carry the semantics. It only adds the qualifier 'verified' and never states expected format, syntax, scope, or length constraints beyond the schema's minLength of 1.

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 ('Add a verified SDK hint') and clarifies the destination ('Affinity's preamble for future sessions'). It does not distinguish this write path from the obvious sibling read path (affinity_search_sdk_hints), so it stops 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?

There is no when-to-use guidance: nothing says to search existing hints first via affinity_search_sdk_hints, nothing defines what 'verified' means, and nothing excludes low-confidence hints. The agent must infer the entire workflow from the name alone.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds the coordinate system (pixels) and default-document behavior, but says nothing about whether the new shape becomes selected, z-order placement, required permissions, or what happens if no document is open.

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 with no filler; the core action and geometry come first, then the fill format, then the document-targeting note. Every clause carries information an agent needs.

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 create-primitive tool with no output schema, the description covers the action, geometry, styling, and document targeting adequately. The remaining gaps are outcome-related (selection/z-order, error when no document exists), which are helpful but not blocking for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain the geometric parameters (x, y, width, height in pixels), the two shape kinds, the #RRGGBB/#RRGGBBAA fill format, and the purpose of session_uuid. It omits that fill is optional and what it defaults to, and does not note the positivity constraint on width/height, leaving minor gaps.

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 ('Add') and resource ('a rectangle or ellipse') plus the coordinate model, so an agent can distinguish it immediately from affinity_add_text (text) and affinity_place_image (image). The scope of the operation is unambiguous.

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

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

The description clarifies targeting behavior ('Defaults to the current document; pass session_uuid to target another'), which is useful context. But it gives no when-to-use vs sibling guidance (e.g. add_shape vs add_text vs execute_script for programmatic creation), nor prerequisites such as needing an open document.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation. The description adds that a new frame is created using the document's default text style, which is useful context beyond the annotations. It does not cover the return value, whether the new frame becomes selected, or what happens if the text overflows the frame.

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

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

Two sentences, no filler, with the core action and coordinate contract front-loaded and the targeting override last. Every clause carries information.

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

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

The description covers inputs and target selection, but with no output schema and no annotation detail on results, an agent still does not know what the tool returns or whether the frame is selected or styled beyond defaults. Adequate but with clear gaps for a mutating creation tool.

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

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

Schema coverage is 0%, so the description carries the full burden and does it reasonably well: it names x, y, width, height, and text, fixes the unit as pixels, and explains session_uuid's targeting role. It does not state that width/height define the frame box rather than the text bounds, which is an inference the agent must make.

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 ('Add a text frame containing text') plus the coordinate model, which separates it from affinity_add_shape and affinity_place_image. It does not explicitly name those siblings, so an agent must still infer the distinction.

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 default target (current document) and the override condition ('pass session_uuid to target another'), which is genuine routing guidance. It says nothing about when to prefer affinity_add_shape or affinity_execute_script for text, and no preconditions 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is largely covered. The description adds real value with 'This can modify documents and access capabilities allowed by Affinity settings,' which discloses mutation scope and permission gating. It says nothing about error behavior, sandboxing, or whether repeated execution is safe, which the non-idempotent hint already implies but leaves unexplored.

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 action and followed by the risk note. No filler, though there is room for a sentence about the script contract without bloat.

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 an arbitrary-code-execution tool with one undocumented parameter, no output schema, and no stated return behavior, the description is thin. It omits what the script receives, what it returns to the caller, and how to discover the available API, all of which an agent needs before invoking it safely.

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 single parameter has 0% schema description coverage and the description adds no meaning: it doesn't say whether the script should be a function body, an expression, or an IIFE; whether it may be async; or what variable names are in scope. With coverage this low, the description needed to compensate and does not.

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: 'Execute JavaScript in Affinity.' It is the only execution-capable tool among the siblings, so the resource is unambiguous. It doesn't define the scope of what 'JavaScript in Affinity' means (API surface, context), which keeps 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?

There is no when-to-use guidance and no mention of alternatives or prerequisites. Siblings like affinity_list_sdk_documentation, affinity_read_sdk_documentation_topic, and affinity_add_sdk_hint exist precisely to support script writing, but the description never routes the agent to them before executing.

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 readOnly=false, idempotent=false, destructive=false, so the description adds real value by disclosing that Affinity's filesystem setting restricts where files can be written and that the Desktop is allowed by default. It also documents the area default of whole_document. It stops short of saying whether an existing file at the path is overwritten or what is returned on success.

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 tight sentences, front-loaded with purpose and format, then area semantics, then the filesystem constraint. The enumeration of formats and areas duplicates the schema enums, which is the only mild waste.

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 four-parameter write tool with no output schema and no annotation detail, the description covers destination semantics and defaults but omits overwrite behavior, whether the parent directory must exist, and any indication of what is returned (path, confirmation, or silent write). That leaves a meaningful gap for an agent preparing a 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 carry the load; it does add meaning for 'path' (must be absolute) and for 'area' (defaults to whole_document), which the bare enum does not convey. However, the format and area value lists largely repeat existing enums, and session_uuid is never mentioned at all.

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 ('Export a document') plus the full set of output formats and the selectable export areas, so an agent immediately knows this writes an image/PDF file. It does not, however, distinguish itself from sibling render tools such as affinity_render_selection and affinity_render_spread, whose apparent purpose overlaps with the 'selection' and 'current_spread' area values.

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 scopes usage by explaining that the target document defaults to the current document and that the filesystem setting constrains writable locations. It never states when to choose this tool over affinity_render_selection or affinity_render_spread, nor any prerequisite for the export directory to exist.

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' read-only, idempotent, and non-destructive guarantees, the description discloses the current-document default and the breadth of state inspected, including fonts and dirty/undo state. It does not explain behavior when no document is current or a session identifier is invalid, but these are minor omissions.

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-load the operation and returned information, then explain optional targeting. Every phrase contributes useful selection or invocation detail without 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?

For a simple, read-only tool with one optional parameter, the description covers the returned content, default target, and parameter usage. Despite the absence of an output schema, the enumerated settings provide enough detail for correct selection and 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?

Although the schema provides no parameter description, the tool description fully explains session_uuid's purpose and the consequence of omitting it. This compensates well for the 0% schema description coverage.

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, "Read a document's setup," then enumerates the exact settings and state returned. Its read-only focus also clearly distinguishes it from the sibling affinity_set_document_settings.

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 targeting guidance: use the current document by default or supply session_uuid for a specific document. It does not explicitly name alternatives or exclusions, but none are essential for this straightforward read 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value by enumerating what is returned (session UUIDs, titles, paths, dirty state), which tells the agent this is a discovery/inspection call rather than a content read.

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 no filler. The scope constraint appears first and the returned fields follow, so the agent gets purpose and payload in one pass.

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 present, the description carries the burden of describing return values, and it does so by naming the four returned fields. It omits ordering, whether only frontmost windows appear, and behavior when no documents are open — minor gaps for a zero-parameter list 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not invent filtering options that the schema does not support.

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 documents currently open in Affinity') and qualifies scope with 'currently open', which separates it from affinity_open_document and affinity_new_document. It stops short of naming a sibling explicitly, so differentiation relies on inference from the verb.

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 'currently open' — an agent can infer this is the inspection call used before acting on a session. However, there is no explicit statement of when to prefer this over affinity_status or affinity_get_document_settings, and no prerequisites or exclusion conditions 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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered and the description does not contradict it. What the description omits is what the listing contains (script names only? metadata? bodies?) and whether results are paginated or capped, which would be useful for a listing 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?

A single short sentence with the verb and resource front-loaded and no filler. It is appropriately sized for a zero-parameter listing 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?

For a zero-parameter, read-only listing tool with annotations and no output schema, the definition is minimally sufficient to invoke it correctly. It is incomplete in that it gives no hint about the shape or scope of the returned list (library-installed scripts vs. bundled examples), which is the main ambiguity an agent would face here.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond the input schema, and the 100% schema coverage baseline applies. Nothing in the description adds or detracts from parameter 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 ('List') and resource ('scripts in Affinity's script library'), so the agent knows exactly what the tool returns at a coarse level. However, it does not distinguish itself from the closely related siblings affinity_read_library_script and affinity_save_script_to_library, which an agent could easily confuse with 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?

There is no explicit when-to-use guidance and no mention of alternatives. The natural workflow (list library scripts, then read one with affinity_read_library_script) is only inferable from the sibling names, not from the description, and nothing says when this is preferable to affinity_list_sdk_documentation.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no statement of whether topics are static or document-version-dependent, no return shape, no pagination note — so it merely restates the title.

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

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

One front-loaded sentence with zero filler; there is nothing to trim. It is minimal rather than artfully structured, but it is appropriately sized for a no-argument 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?

For a zero-parameter read-only list this is close to adequate, but it omits the one thing that would help an agent act on the result: that the returned topic identifiers are what affinity_read_sdk_documentation_topic consumes. There is no output schema to cover that 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; there are no parameter semantics for the description to compensate for.

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') with a clearly scoped resource ('Affinity SDK documentation topics'), which is unambiguous. It does not mention that the listed topics are the inputs to affinity_read_sdk_documentation_topic, so the sibling distinction is left to the tool names rather than stated.

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

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

There is no when-to-use guidance, no prerequisite, and no reference to the obvious alternative affinity_read_sdk_documentation_topic. An agent must infer that this is the discovery step preceding a read.

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 a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavior beyond that: save_as is optional and the tool returns a session UUID for later tools. It stops short of explaining overwrite behavior when save_as targets an existing file, which would be useful 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?

Two sentences, front-loaded with the core action and modes, then the return value. Every clause carries useful information and nothing is repeated from structured fields.

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 document-creation tool with annotations and no output schema, the description is nearly complete: it covers creation modes, optional saving, and the returned session UUID. The main omission is what happens if save_as points to an existing document.

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 coverage at 100%, the baseline is 3, but the description adds meaningful semantics not obvious from the schema: preset examples such as 'A4', 'IG Post', and 'Icon', and the anyOf choice between preset mode and explicit dimension mode. It also clarifies that save_as is optional. The dpi parameter is left unexplained, keeping it from a 5.

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

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

The description uses a specific verb and resource ('Create a new Affinity document') and clearly separates creation from opening existing documents. It also states the two construction modes and the returned handle, so an agent can identify the tool 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 clearly explains the two valid creation modes: a named preset or explicit width, height, and units, with optional save_as. It does not explicitly name when to use this instead of sibling tools such as affinity_open_document, but the 'new' scope makes the distinction reasonably 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 already cover mutability and idempotency, but the description adds real behavior the annotations cannot: it will launch an external application, it blocks until the local connector is ready, and it establishes a connection. What it does not disclose is failure behavior or any timeout/retry characteristics when the launch or connector wait fails.

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, action sequence front-loaded, and the second sentence immediately qualifies necessity. No filler or restatement of the tool name.

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, no-output-schema tool this covers the essentials: what it launches, what it waits on, and why an agent might call it. It stops short of saying what the call returns or does on failure, which would be the only remaining gap.

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

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

The tool takes zero parameters, so there is no parameter meaning to add; the baseline for a no-param tool is 4. The description correctly implies there is nothing to configure.

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 sequence of actions on a named resource: launch Affinity if not running, wait for the local MCP connector, then connect. That is clearly separable from sibling tools like affinity_status (which presumably only reports state) and affinity_open_document (which opens a file).

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 ('warm Affinity up ahead of time') and an explicit when-not-to-bother ('Other tools do this automatically'), which tells the agent this call is optional and latency-motivated rather than required before other calls.

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, it discloses the already-open behavior and a non-obvious filesystem restriction, including that Desktop is readable by default. It does not explain errors for inaccessible or invalid paths, but it provides meaningful operational context for a simple 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?

Two short sentences front-load the operation and then state the key filesystem constraint. There is no filler or unnecessary repetition of structured fields.

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 tool, it covers the main operation, duplicate-open behavior, and principal access restriction. Sibling disambiguation and error or return details remain absent, but the description is sufficient for correct basic 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 0% schema description coverage, the description usefully explains that path must be absolute, identify an existing document, and reside in a readable location. The Desktop default adds concrete guidance, although an example path or supported-file guidance could help further.

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: opening an existing document from an absolute path. "Existing" helps distinguish it from affinity_new_document, but it does not clarify how this tool differs from the similarly named affinity_open 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?

It provides clear usage context: supply an absolute path to an existing document, and an already-open document is simply returned. It does not name alternatives or explain when affinity_open should be preferred.

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 cover the write/safety profile (readOnly=false, idempotent=false, destructive=false); the description adds genuinely non-obvious behavior: Affinity's filesystem setting restricts readable folders and Desktop is allowed by default. It does not disclose whether repeated calls create duplicate layers (relevant given idempotentHint=false) or failure behavior for disallowed paths.

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 compact sentences, front-loaded with the action, then the placement mode, then the environment constraint. No filler; the filesystem caveat 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?

Six parameters with zero schema descriptions and no output schema mean the description must carry more weight. The unexplained session_uuid and absent return-value behavior (e.g., whether a layer reference is returned) leave real gaps for a mutating placement tool.

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

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

With 0% schema description coverage, the description does meaningful work explaining that x/y/width/height define a fit rectangle and their omission yields natural size. However image_path's accepted format (relative vs. absolute, allowed roots) and session_uuid's purpose are left entirely undefined.

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: 'Place an image file into the document.' The image-file target implicitly separates it from affinity_add_shape and affinity_add_text, though no sibling is named 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?

Useful conditional guidance on the two placement modes (rectangle-fit vs. natural size) and the default target document ('Defaults to the current document'). It does not say when to choose this over affinity_add_shape or how session targeting relates to siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered by structured data and the description is not obliged to restate it. Beyond that, the description adds no behavior — nothing about what is returned (script source vs. metadata), or what happens when the title does not exist.

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. Brevity is appropriate here, though the terseness leaves the gaps noted in other dimensions rather than earning extra credit.

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

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

A one-parameter read tool with full annotation coverage and no output schema needs little, but the absence of return-value expectations and not-found behavior leaves an agent guessing at the result shape after a successful 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% for the single 'title' parameter, so the description carries the burden; 'named script' does imply the parameter is the script's library name, which is a small but real addition over a bare 'title' string. It still says nothing about exact-match vs. fuzzy lookup or case sensitivity.

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-plus-resource: read a named script from Affinity's script library. An agent can tell it apart from affinity_list_library_scripts (enumerate) and affinity_save_script_to_library (write) without opening schemas, though no sibling is named 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?

No when-to-use guidance, no prerequisites, and no routing to affinity_list_library_scripts for discovering valid titles or to affinity_execute_script for running the result. The workflow (list, then read by title) must be inferred 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that: it does not say whether the filename must match exactly, whether an unknown filename errors or returns empty, or what the returned content looks like.

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

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

One front-loaded sentence with zero padding — nothing is wasted. However, the brevity reflects under-specification rather than disciplined compression, so it falls short of a 5.

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 structurally simple (one string parameter, no output schema), which lowers the bar, but the two things an agent actually needs — the filename format and the discovery path via affinity_list_sdk_documentation — are both absent. Annotations cover the safety profile, yet the core invocation guidance 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 description coverage is 0%, so the description carries the burden for the single required parameter, but it only restates 'by filename.' It does not specify the filename format (extension? path? slug?) or how to discover valid values, leaving the agent unable to construct a valid call without trial and error.

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 an Affinity SDK documentation topic by filename.' This is clearly distinguishable from affinity_list_sdk_documentation (which enumerates topics) and affinity_search_sdk_hints (which searches hints), though the description never explicitly names those siblings.

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

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

There is no when-to-use guidance, no mention of calling affinity_list_sdk_documentation first to obtain a valid filename, and no exclusion relative to affinity_search_sdk_hints. An agent must infer the workflow entirely from 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds the output format (JPEG), which is useful, but with no output schema it never says how the image is delivered (base64 payload, file path, or attachment) or what happens when nothing is selected.

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 short, front-loaded sentence with no wasted wording. Its brevity is appropriate in form, though it leaves substantive gaps that the other dimensions penalize.

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 annotation of return behavior, the description should explain what the render returns and what 'selected nodes' means (current user selection in the open session). Neither is addressed, leaving a render tool's result contract undefined.

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 single parameter document_session_uuid has 0% schema description coverage and the description never mentions it. It does not clarify that the UUID identifies the document session whose selection is rendered, so the description adds no meaning beyond the parameter's name.

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

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

The description uses a specific verb plus resource ('Render the selected nodes ... as a JPEG'), which tells an agent exactly what the tool produces. It does not explicitly distinguish itself from the sibling affinity_render_spread, which renders a whole spread rather than a selection, so the boundary is left implicit.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no pointing at affinity_render_spread or affinity_export as the alternatives for whole-spread or file export. The agent must infer the choice from the tool name alone.

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 readOnly/idempotent/non-destructive, so safety is handled. Beyond that the description says nothing about what comes back — raw bytes, a file path, or an inline image — nor about resolution, format options, or failure behavior for an out-of-range index.

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 no filler. It is compact but arguably too terse given the missing return-value 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?

With no output schema and no annotations about output, the description leaves the most important question unanswered: what the caller receives from a render call. For a rendering tool this is a substantial omission.

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

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

Schema coverage is 0%, so the description must carry the parameter load. It adds a useful clarifier that the spread index is zero-based, but does not explain how document_session_uuid relates to an open session or what a spread is in this context.

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 ('Render'), a concrete resource ('spread in a document session'), and the output format ('JPEG'). It is distinguishable from affinity_render_selection by naming 'spread', though it never explicitly contrasts with 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?

No indication of when to use this versus affinity_render_selection or affinity_export, nor any prerequisite such as needing an open document session first. The agent must infer the routing from the sibling names alone.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive operation, so the safety profile is known. The description adds that the issue must be 'confirmed' and that a code reproduction is optional, but it doesn't say where the report goes, whether it leaves the local environment, or what happens if the same issue is reported twice despite idempotentHint=false.

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

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

One front-loaded sentence with no filler; the verb and resource lead. The economy is fine, though the single sentence is doing little beyond the name.

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 two-parameter submission tool with no output schema, the description doesn't explain what a caller gets back (confirmation, ticket ID, nothing) or what a good 'description' payload looks like. Given the tool's low complexity, the minimum viable bar is met, but only just.

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 both parameters, so the description carries the full burden and only partially meets it: it identifies 'code' as optional reproduction code but never says what 'description' should contain (steps, expected vs actual, version). 'description' is also the required field, and that requirement is not reinforced or elaborated.

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: 'Report a confirmed Affinity SDK issue', which is distinct from the SDK documentation/hint siblings. It doesn't explicitly contrast with affinity_add_sdk_hint, which is the closest-looking alternative, but the action and object are unambiguous.

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

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

The word 'confirmed' implies the issue should be verified before reporting, but no explicit when-to-use or when-not-to-use conditions are given. It never mentions affinity_add_sdk_hint or affinity_search_sdk_hints, so an agent has to guess whether reporting an issue and adding a hint are different actions or the same.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, so the agent knows this is a mutating, non-idempotent write. The description, however, never mentions overwrite risk, whether saving the same title twice duplicates or replaces, or any prerequisites such as an open document — all of which are critical for a destructive write. It reads as a harmless additive 'save' and masks the risk the annotations 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is the direct cause of the missing behavioral and parameter 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 destructive, non-idempotent mutation with three undocumented parameters and no output schema, the description supplies only the barest statement of intent. It omits overwrite behavior, error conditions, and what the tool returns, so an agent cannot call it confidently without trial and error.

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?

All three parameters have 0% schema description coverage and no required/enum hints in the schema beyond type and minLength. The description adds no meaning to title, description, or code, leaving the agent with no idea of expected format, length, or content conventions for any of them.

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 (save a script to the script library), which is clearly distinct from affinity_execute_script and affinity_read_library_script by name. It stops short of explicitly contrasting with those siblings, but the action is unambiguous.

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

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

The word 'completed' hints that only finished scripts belong here, but there is no guidance on when to save versus execute directly, whether saving is required before execution, or what happens if a script with the same title already exists. The agent must guess the workflow position of this tool.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with a safe search operation. It adds minor context that hints are "shared" and intended for an "existing solution," but does not describe result format, matching behavior, or limits.

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

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

The description is a single front-loaded sentence with no wasted wording. Its brevity is appropriate structurally, even though it leaves important details unspecified.

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 search tool with no output schema, the description should clarify what is returned and how results are matched. It does not explain what an SDK hint contains, whether results are ranked, or what the prompt should contain, so it is not complete enough to guide 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 the single undocumented "prompt" parameter. It only implies that the prompt relates to an existing solution; it does not explain whether the prompt should be natural language, an error message, code, or a feature description.

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

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

The description uses a specific verb and resource: "Search shared Affinity SDK hints." It is distinguishable from sibling tools such as affinity_add_sdk_hint and affinity_list_sdk_documentation, though it does not explicitly contrast itself with affinity_read_sdk_documentation_topic.

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 no explicit guidance on when to use this search tool versus reading SDK documentation topics or listing library scripts. The phrase "for an existing solution" hints at a use case but does not define when-not-to-use conditions or 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 only say destructiveHint=true and idempotentHint=false; the description adds the actual mechanism: changing dpi, size, or transparency rewrites document setup, other settings are preserved, and background transparency silently resets to opaque unless transparent_background is passed. That is exactly the side-effect an agent needs to know before calling a destructive mutation.

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 action and then the side effects, with no filler. It is dense but each sentence carries information; a slight tightening of the "Supports units, dpi..." clause would make it cleaner.

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 six-parameter destructive mutation with no output schema, the description covers the return (updated settings), all parameters, the default target, and the destructive rewrite behavior. What is missing is minor: no note on whether a failure leaves the document partially rewritten, and no explicit mention that session_uuid is optional beyond the default phrasing.

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, and it names all six parameters including the session_uuid targeting rule and the conditional effect of transparent_background. It does not explain unit semantics or the exclusiveMinimum bounds on dpi/width/height, leaving some meaning to the schema's 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?

"Change a document's setup and return the updated settings" gives a specific verb (change/set) plus resource (document setup) and enumerates the supported settings (units, dpi, width/height, transparent_background). It is clearly the mutation counterpart to affinity_get_document_settings, 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?

"Defaults to the current document; pass session_uuid to target a specific one" gives concrete targeting guidance and a default behavior. It does not state when to avoid this tool or point at alternatives (e.g. affinity_new_document for creating rather than modifying), 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?

The annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful operational context by identifying the local MCP connector dependency and confirming that checking status will not launch Affinity, though it does not discuss error 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 short sentences front-load the exact purpose and then provide the essential non-launch caveat. There is no filler or redundancy.

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

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

For a zero-argument, read-only status check, the description and annotations provide nearly everything needed to select and invoke the tool. Because there is no output schema, it could additionally clarify the status response shape or disconnected/error handling, but these are minor 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?

There are no parameters, and the empty schema with additionalProperties disabled fully specifies invocation. No parameter explanation is necessary, so the zero-parameter baseline 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?

The specific verb "Report" and the resource—adapter connectivity to Affinity's local MCP connector—make the purpose unambiguous. It is clearly distinct from the document-oriented siblings, and "Does not launch Affinity" further separates it from affinity_open.

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 establishes its use as a connectivity check and explicitly rules out using it to launch Affinity. It does not name affinity_open as the alternative or describe a recommended preflight workflow, so the routing guidance is not fully explicit.

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