Pane

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

The description reveals important behavioral traits beyond annotations: whoami is no-network/no-secrets, claim is one-way, logout clears locally but does not revoke. These details add significant context to the destructiveHint=true annotation, clarifying what is destructive and what is not.

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 highly concise, two sentences front-loading the core purpose and then detailing each action. Every sentence is informative, with no redundancy or wasted words.

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

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

Overall, the description covers the tool's actions, side effects, and cross-references well. However, it does not describe the return value or error conditions, and it mentions that code is required for claim but the schema lists it as optional, leaving a slight ambiguity. Nonetheless, for a tool with no output schema and moderate complexity, it is mostly complete.

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

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

The input schema has 100% description coverage, so the parameter descriptions are already present in the schema. The tool description adds little beyond summarizing the action enum, providing no new parameter-level details. Thus, baseline 3 is appropriate.

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

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

The description clearly states the tool manages agent identity and binding, explicitly listing three distinct actions (whoami, claim, logout) with specific scopes. It distinguishes itself from the sibling 'key' tool by noting that logout does not revoke on the relay, referencing the key tool for that purpose.

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

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

The description provides explicit when-to-use guidance for each action: whoami for identity info without network/secrets, claim for one-way binding with a claim code, and logout for local clearing. It also advises when not to use it (for revocation, use the key tool), giving clear alternatives.

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

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

The description discloses key behavioral traits such as absolute paths for upload/download, scope defaults, soft-delete for delete, one-time minting of tokens, and base64 fallback for download. Annotations ('destructiveHint': true) are consistent, and the description adds context beyond annotations, though it omits details like pagination behavior for list.

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 dense paragraph that efficiently covers purpose, actions, key behaviors, and scoping. Every sentence earns its place with no redundancy, and the critical information is front-loaded.

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

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

Given the complexity of 14 parameters and 8 actions with no output schema, the description covers most crucial behaviors (upload, download, mint_token, scoping) but omits some details like the return format for list or download without out_path (though hinted). It is fairly complete but not exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3. However, the tool description adds extra meaning by explaining how parameters interact (e.g., scope affects required pane_id/template_id, upload reads absolute file_path, download returns base64 when out_path omitted). This adds value beyond the schema.

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

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

The description clearly identifies the tool as managing binary attachments with a specific list of actions. It distinguishes itself from sibling tools by being the only one handling attachments, and provides a clear verb+resource description.

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

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

The description implies usage for attachment management but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The sibling list suggests no other tool does attachments, so usage is implied but not clearly guided.

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 provide readOnlyHint=false, destructiveHint=true, etc. The description adds important behavioral details: the relay hosts and returns a URL, idempotency via context_key, lifetime via ttl_seconds, and event/record mutation. It does not contradict annotations. A high score but not 5 because annotations carry some of the burden.

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 moderately long but well-structured. It front-loads the core purpose, then provides usage guidance, then detailed parameter notes. Every sentence adds value, though some could be tightened. Overall, it balances completeness with readability.

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

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

For a complex tool with 18 parameters and no required ones, the description is remarkably complete. It covers two usage modes, event/record schemas, return fields, and references sibling tools (get_skill, taste, get_events, template). Without an output schema, it still describes what is returned. The description leaves little ambiguity for an agent.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains when to use html+name vs template_id, how events work (window.pane.emit), and the relationship between parameters. For example, it clarifies that name is required with html but omitted with template_id. This significantly aids parameter selection and correct invocation.

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

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

The description clearly states the tool's purpose: creating a rich interactive UI by URL. It specifies the verb ('Hand'), resource ('UI'), and distinguishes between inline HTML and template modes. It also lists use cases (forms, approvals, etc.), making it easy for an agent to understand when to use this tool. No ambiguity.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'Reach for this whenever a text reply is the wrong shape' and lists specific scenarios. It advises calling get_skill and taste before authoring, and mentions alternatives like get_events and record tools. This helps the agent decide correctly.

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

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

Annotations already indicate idempotent and destructive; description adds that the human's URL stops working, providing extra context beyond annotations.

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

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

Three concise sentences with no wasted words, front-loaded with the main action, then side effects and guidance.

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 tool with one parameter, the description covers purpose, behavior, side effects, and sibling differentiation; no output schema needed.

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

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

Schema coverage is 100% with a clear description of pane_id; the description echoes the idempotent behavior but adds little beyond the schema.

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

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

The description clearly states the action ('Close/delete a pane') and the resource, and distinguishes from siblings by mentioning alternatives (update_pane, trash).

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

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

Explicitly provides when to use (delete) and when not (edit via update_pane, restore via trash), plus notes idempotency.

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

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

The description adds value beyond annotations by explaining it's a soft-delete with a tombstone in list_records and that the page sees the deletion live. Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description aligns with them without contradiction.

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

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

Two sentences with no filler. The first sentence states the core purpose and effect, the second gives an optional usage hint and return value. Efficient and well-structured.

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

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

Given no output schema, the description includes the return object ({ deleted: true }) and explains the soft-delete behavior. It could mention error scenarios or whether the operation is reversible, but for a delete tool, it covers the essential aspects.

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 100% schema coverage, baseline is 3. The description adds meaningful context for the 'if_match' parameter (optimistic-locking) and implies the purpose of pane_id, collection, and record_key from their names. This lifts it above baseline.

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

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

The description clearly states the verb 'soft-delete' and the resource 'row from a pane's record collection'. It distinguishes from sibling tools like delete_pane and delete_record_collection by specifying soft-deletion behavior and noting the tombstone effect in list_records.

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 a conditional guideline by mentioning 'Pass if_match for an optimistic-locked delete'. While it does not explicitly list alternatives or when-not-to-use, the context of soft-deletion versus other delete operations is clear.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but description adds 'owner-only', 'requires confirm:true', and 'returns { deleted: true, collection }'. No contradictions with annotations; idempotentHint=true is not addressed but not contradicted either.

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

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

Three sentences, each serving a distinct purpose: function definition, usage guidance, and behavioral note. No wasted words, front-loaded with the core action.

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

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

Given no output schema, description still mentions return value. Covers destructive nature, ownership, confirm requirement, and alternative tool. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds context about collection immutability and confirm requirement, but mostly repeats schema info. Baseline 3 is appropriate.

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

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

The description uses specific verb 'drop' and resource 'record collection', clearly distinguishes from sibling 'delete_record' by mentioning bulk vs single deletion. The title 'Delete Record Collection' is also clear.

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

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

Explicitly states when to use ('reset or remove a collection') and when not ('rather than deleting rows one by one with delete_record'). Also specifies requirement of confirm:true and owner-only restriction.

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

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

Annotations already indicate destructiveHint=true. The description adds behavioral details: list returns newest first, paginated with 'before' cursor, limit defaults to 50 max 100, and optional pane_id for create. It does not mention authentication or side effects beyond mutation, which is acceptable.

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 extremely concise: two sentences that front-load the purpose and then detail actions. Every word is necessary; no redundancy. It is a model of efficient tool 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?

Given the tool's complexity (two actions, no output schema, high schema coverage), the description covers the core functionality well. It explains create and list with parameters and pagination. Minor gap: missing return format for list, but acceptable without output schema.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description adds integration context (e.g., action enum purpose) but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's dual purpose: send (create) or list feedback. It specifies the action enum and the feedback categories (bug, feature, note) with optional pane_id. This differentiates it from sibling tools, none of which handle feedback.

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 when to use create (to submit feedback) vs list (to view the agent's own submissions, paginated). It provides context but does not explicitly exclude scenarios or mention alternatives. However, given sibling tools, no alternative exists for feedback.

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 readOnlyHint annotation, the description reveals critical behavioral traits: the event log is append-only, the polling loop pattern, the return of events and next_cursor, and the long-polling mechanism with wait_seconds. It also warns about the lack of push/streaming. No contradictions with annotations.

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

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

The description is concise, with two short paragraphs. The first paragraph states the purpose and the polling pattern; the second explains the wait_seconds option and return shape. Every sentence is informative, and the structure is front-loaded with the essential purpose.

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

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

Given the tool's complexity (polling with cursor, long-polling), the description is remarkably complete. It explains the initial call, subsequent calls with cursor, the optional wait_seconds, and the return structure. There is no output schema, but the description mentions the return shape. It is sufficient for an agent to use the tool correctly.

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

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

The input schema already describes all three parameters with 100% coverage. The description adds value by explaining the usage semantics: 'since' is an opaque cursor from a previous call, 'pane_id' identifies the pane, and 'wait_seconds' is for long-polling. It ties parameters to the polling pattern, adding meaning beyond the schema.

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

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

The description clearly states the tool polls a pane's append-only event log for human actions (form submissions, approvals, picks). It specifies the verb 'poll' and resource 'event log', and distinguishes it from other tools by explaining it's the way to receive round-trip results in MCP. The purpose is unambiguous and specific.

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

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

The description provides explicit instructions for usage: poll with no 'since' first, process events, use next_cursor for subsequent calls, and optionally use wait_seconds for long-polling. It mentions there is no push/streaming in MCP, implying this is the alternative. However, it does not explicitly state when not to use this tool or list alternative tools for different scenarios.

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, so safety is known. The description adds useful context about what is returned (metadata fields) and explicitly states what is excluded (event log), which goes beyond annotations.

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

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

Two concise sentences, front-loaded with the action and resource, followed by usage guidance. Every sentence is necessary and well-structured.

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

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

Given a single parameter, no output schema, and clear annotations, the description fully covers the tool's purpose, what it returns, and when to use it. No gaps remain.

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 is only one parameter (pane_id) and the schema description already provides adequate explanation: 'The pane id returned by create_pane.' With 100% schema coverage, the description adds no additional 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?

The description clearly states the verb 'Fetch' and the resource 'pane's current metadata' (status, title, template version, timestamps, expires_at), and distinguishes itself from get_events by specifying it does not include the event log.

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

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

Explicitly says when to use: 'to check whether a pane is still open or has expired', and when not to use: 'to read what the human did, use get_events'. Provides a clear alternative.

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

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

Beyond the readOnlyHint annotation, the description adds that the tool 'scans the collection' and describes the return format ({record} or isError). This provides valuable behavioral context without contradicting 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?

Two concise sentences front-load the action and provide key details about performance and output. No extraneous words.

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

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

For a simple fetch tool with 3 well-documented parameters and annotations, the description covers purpose, usage context, behavior, return format, and limitations. With no output schema, the description adequately explains the return value.

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 descriptions already cover each parameter (pane_id, collection, record_key) with clear definitions. The description does not add new semantic meaning beyond the schema, so it meets the baseline for 100% schema 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?

Description clearly states 'Fetch a single record row by its key from a pane collection', which is a specific verb and resource. It distinguishes from sibling tools like list_records and upsert_record by focusing on a single record fetch, though not explicitly naming alternatives.

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

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

Provides usage guidance by stating 'fine for a one-off lookup, not a hot loop' and implies appropriate context. Does not mention alternative tools explicitly, but the performance note helps in decision-making.

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

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

Annotations declare readOnlyHint=true, and description adds critical behavioral details: unauthenticated, no API key needed. Also explains version_only parameter behavior for caching. No contradictions.

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

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

Description is brief (two sentences), front-loaded with core purpose, and every sentence serves a distinct function (purpose, usage context, parameter explanation). No 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?

With one optional parameter and no output schema, description fully covers behavior: returns full SKILL.md or version string. Sufficient for agent to select and invoke correctly.

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

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

Schema covers the version_only parameter with 100% coverage. Description adds value by explaining its purpose: 'to check if a cached copy is stale', which aids agent decision-making beyond schema.

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

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

Description clearly states 'Fetch the relay's auto-updating SKILL.md' and specifies it's unauthenticated. Distinguishes from siblings by framing it as a self-teaching guide for the Pane workflow before using other tools.

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

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

Explicitly states 'Call this to self-teach the Pane workflow... before driving the other tools', providing clear when-to-use guidance. No explicit when-not or alternatives, but context implies it's the primary reference tool.

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

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

Annotations already indicate destructiveHint=true. The description adds further transparency by explaining that revoke is immediate, irreversible, and scoped to the caller's own key. It does not contradict annotations and provides behavioral context beyond the structured fields.

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

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

The description is extremely concise with two sentences. The first sentence states the overall purpose, and the second elaborates on actions. No unnecessary words, making it efficient for an AI agent to parse quickly.

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

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

Given no output schema, the description covers return values for 'list' (key info fields). For 'revoke', it warns about immediate effect but does not specify the return format (e.g., success message). The tool has only 2 parameters, and the description addresses their usage adequately, with only a minor gap on revoke's output.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by specifying what 'list' returns (agent_id, key_prefix, timestamps) and that 'revoke' requires confirm:true and is irreversible, adding meaning beyond the schema's enum 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 clearly states the tool inspects or revokes the calling agent's API key, with specific actions listed. It distinguishes itself from sibling tools by focusing solely on key management, and the verb 'manage' plus resource 'API key' is specific and 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 provides explicit context for when to use each action: 'list' for key info (agent_id, key_prefix, timestamps) and 'revoke' for self-destructing the key. It includes important warnings about irreversibility and the need for confirmation, though it does not explicitly state when NOT to use the tool or mention alternative tools.

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

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

Annotations declare readOnlyHint=true; description adds key behavioral context: 'No secrets in the response (participant tokens are unrecoverable — mint a fresh URL with the participant tool)' and returns { items, next_cursor }. No contradiction.

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

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

Three sentences, front-loaded with core purpose, each sentence adds value (use cases, secret disclosure, filtering, return format). No wasted words.

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

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

Covers purpose, usage, return shape, and key behavioral info. No output schema; description mentions items and next_cursor. Small gap: items structure not described, but adequate for listing tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about unrecoverable tokens and cursor pagination, but doesn't significantly enhance parameter understanding beyond schema.

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

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

Clearly states 'Enumerate YOUR agent's panes (newest first)' with specific use cases (find lost pane_id, audit open panes, get pagination cursor). Distinguishes from sibling tools like get_pane_state, create_pane, delete_pane, update_pane by indicating listing functionality.

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

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

Provides explicit use cases: find pane_id, audit open panes, get pagination cursor. Mentions filtering options. However, lacks explicit when-not-to-use or alternatives among 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 indicate readOnlyHint=true. The description adds value by explaining the polling behavior, the effect of include_tombstones, and the return shape. It does not disclose rate limits or auth requirements, but for a read-only tool, the key behaviors are covered.

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

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

The description is concise (3 sentences), front-loaded with the main purpose, and each sentence adds value. No redundancy or fluff.

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

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

Despite no output schema, the description specifies the return shape ({ records, next_since, has_more }). It covers polling, filtering, and deletion observation. For a list tool, this provides sufficient context for accurate 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 coverage is 100%, but the description enriches parameters: it explains 'since' as a cursor and polling handle, 'include_tombstones' for deletions, and 'limit' as page size. This adds significant meaning beyond the schema descriptions.

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

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

The description clearly states the tool lists rows in mutable record collections, provides examples (todo list, shopping list), and distinguishes it from history-focused tools. It also notes it doubles as a poll/watch mechanism, making the purpose 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 explains when to use this tool ('when CURRENT state matters more than history') and how to poll by passing next_since. However, it does not explicitly contrast with siblings like get_record or update_record, leaving some usage ambiguity.

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

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

The description adds important behavioral details beyond annotations: token URLs are stored hashed and cannot be recovered, plaintext token is returned only once, and list shows both active and revoked participants. This enriches the agent's understanding of safety and data handling.

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 four sentences long, front-loads the core purpose, and contains no redundant or vague statements. Every sentence contributes valuable 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?

Given no output schema, the description adequately covers important behavioral aspects (token return once, irrecoverability). It explains each action's purpose. Minor gap: no mention of what list returns, but the schema's enum description covers that.

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

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

Schema coverage is 100%, but the description adds context to the action enum (e.g., 'list: every participant...', 'new: mint a FRESH human URL...') and clarifies that participant_id is required for revoke. This goes beyond the schema's basic descriptions.

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

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

The description clearly states it manages participant URLs for a pane, listing specific actions (list, new, revoke) and their purposes. It distinguishes itself from sibling tools by focusing on participant URL management.

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

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

The description gives explicit guidance for when to use 'new' (when original URL lost) and explains that tokens cannot be recovered. While it doesn't explicitly name alternatives, the tool's focus is clear enough for an agent to infer appropriate usage context.

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

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

Annotations already declare readOnlyHint=true. The description adds valuable behavioral details: default output format, row caps (10k rows), timeout (10s), scoping to owned panes, and view conflict resolution via pane_id. No contradictions with annotations.

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

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

Three sentences, each earning its place: first sentence states purpose and scoping, second lists use cases and references parameter documentation, third describes output format and caps. No wasted words, front-loaded with the core action.

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

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

Given 3 parameters and no output schema, the description is fairly complete: it covers input (tables, operators), scoping, output format, row cap, timeout, and default output fields. It could mention error handling or that SQL errors are returned, but overall is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it documents available tables and JSON operators for the sql parameter, explains output format behavior, and describes pane_id's role in resolving view conflicts. This provides context not present in the schema alone.

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

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

The description states a specific verb ('Run read-only SQL'), identifies the resource ('YOUR scoped data (panes, records, events)'), and provides concrete use cases ('summarise activity, find panes/records by content, or build a report'). It clearly distinguishes from sibling tools by emphasizing the read-only and scoped nature.

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

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

The description gives explicit context on when to use: for read-only queries over scoped data. It implies alternatives (modification tools) through the readOnlyHint and sibling list, but does not explicitly name alternatives. The use cases and the scoping explanation help the agent decide.

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?

Description adds behavioral context beyond annotations: mentions that it updates live UI, returns { event, deduped }, and explains dedup behavior with idempotency_key. No contradiction with annotations.

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

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

Two sentences, no wasted words, front-loaded with purpose. Highly efficient.

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

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

Given no output schema, description mentions return value. Covers purpose, usage, behavioral, and parameter nuances. Missing some edge cases but sufficient for a 4-param 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 100%, baseline 3. Description adds nuance: for data mentions using {} or null for no-payload event, for type adds context about pane's event_schema requirement, for idempotency_key explains dedup.

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

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

Clearly states verb ('push an event') and resource ('open pane') and distinguishes from sibling tools like record tools. Also mentions updating live UI, which is specific.

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

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

Explicitly states when not to use (prefer record tools for mutable collections) and gives requirement (event type must be declared in pane's event_schema with 'agent' in emittedBy). Provides clear 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 signal destructive hint, and the description adds behavioral context by explaining the token independence ('Token (/s/<token>) links are independent of access_mode and keep working'). However, it does not elaborate on potential destructive outcomes or permission requirements beyond what annotations already indicate.

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

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

The description is concise with two sentences that pack essential information. It could be more structured (e.g., bullet points), but it remains clear and front-loads the key purpose. Every part 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?

With 6 parameters, 2 required, no output schema, the description covers the main behaviors of the four actions and the token independence. It lacks explicit details on permissions or error states, but for a tool with an action enum and good annotations, the description is largely 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 100%, so baseline is 3. The description adds value by explaining the token independence and the layering concept, providing context beyond the schema's parameter descriptions. This extra semantic context helps the agent understand the behavior of the tool's parameters.

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

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

The description clearly identifies the tool as managing identity sharing on a pane, with a clear enumeration of four specific actions (list, invite, set_access, revoke). It distinguishes itself from sibling tools by specifying it's layered on top of participant tokens and that token links are independent, setting it apart from related tools like 'participant' or 'send_to_pane'.

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 that all sharing actions should be performed via this single tool, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., the 'participant' sibling tool). No when-not-to-use conditions or exclusions are stated, leaving the agent to infer usage context.

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

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

Discloses that set does whole-document replace (not append) and clear deletes, adding context beyond annotations. Annotations indicate destructiveHint=true, and description aligns with that, no contradiction.

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

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

Two sentences, front-loaded with actions and purpose. Every sentence earns its place; no redundancy or fluff.

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

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

For a simple tool with 2 params and no output schema, the description covers purpose, actions, usage, and behavior. Minor omission: no mention of return values, but given no output schema, it's acceptable.

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

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

Schema coverage is 100%, so baseline is 3. Description adds clarity that taste is required for set (not in schema's required array) and that set is whole-document replace, adding value beyond schema.

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

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

The description clearly states the tool manages UI taste notes with three actions (read/write/clear). It explicitly differentiates from siblings by being the only tool for this purpose, using a specific verb and resource.

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

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

Provides explicit when to call: 'Call get BEFORE generating a pane'. Warns about set behavior (whole-document replace, not append). Also advises to keep entries about UI/presentation only, guiding appropriate use.

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

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

Annotations already indicate destructiveHint=true, and the description elaborates by specifying that delete is destructive and requires confirm:true. It also explains the template lifecycle and relationships, adding value beyond the annotations.

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

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

The description is well-structured and front-loaded with the core concept. It is slightly long but every sentence adds value; no redundancy. It could be slightly shorter but is still efficient.

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

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

Given the tool's complexity (21 parameters, 12 actions, nested schemas), the description covers the essential concepts and relationships with sibling tools. It lacks an output schema but the description implies return types for actions. Overall, it is sufficiently 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 100%, so baseline 3. The description adds substantial meaning by fully explaining the action enum's semantics and required fields per action, and provides context for other parameters like id, confirm, etc.

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

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

The description clearly states it manages reusable, versioned UI templates with a specific action enum. It distinguishes itself from sibling tools by mentioning create_pane's template_id and template_records, making the purpose 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 provides detailed guidance on when to use each action via the action parameter's description, and indirectly references sibling tools. However, it lacks explicit 'when not to use' statements, so it's very good but not perfect.

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?

Description indicates mutability (CRUD) and destructive potential, consistent with annotations (destructiveHint=true). Adds context about scope and prerequisite beyond annotations.

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

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

Two sentences with high information density. Front-loaded with key purpose. Every sentence is necessary, though slightly dense.

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?

Covers usage context, distinctions, and prerequisites well. No output schema, but CRUD behavior is standard. Slightly lacking in return value description.

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

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

Parameter descriptions in schema are comprehensive (100% coverage). The tool description adds value by explaining the action pattern and prerequisite, going beyond schema.

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

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

Clearly states 'CRUD for TEMPLATE-level record collections' and distinguishes from per-pane records. Lists action enum and emphasizes scope (owner-curated, shared across panes).

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

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

Explicitly contrasts with per-pane records and mentions prerequisite (template_record_schema via template tool). No explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate destructiveHint=true. The description adds context: soft-deleted rows live in trash until reclaimed, and purge is permanent. No contradiction with annotations.

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

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

Two sentences, no redundancy. Key information (action enum, effects) is front-loaded. Every sentence adds necessary 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?

Given no output schema, the description adequately covers behavior: all actions and their permanence. Could mention return format (e.g., list returns items) but not essential.

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

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

Schema coverage is 100%, but the description adds value by explaining that id can be a pane id or template id/slug depending on action, and that purge bypasses retention. The description elaborates on the enum values beyond the schema.

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

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

The description clearly states the tool manages soft-deleted panes and templates, with specific actions (list, restore, purge, etc.) and parameters. It is distinct from sibling tools like delete_pane or delete_record, which handle immediate deletion, not trash management.

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

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

The description explains each action (list, restore, purge) and their effects, including that purge bypasses the retention window. It doesn't explicitly state when not to use the tool, but the action enum structure guides appropriate usage.

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

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

The description reveals non-minting, retention of id/URL/event log/template pin, wholesale replacement of input_data with revalidation, and mutual exclusivity of ttl_seconds and expires_at. Annotations provide destructiveHint and idempotentHint, and the description adds valuable context beyond them. Could mention authorization or rate limits for 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?

The description is two sentences, front-loading the key behavior in the first sentence and listing settable fields and returns in the second. No redundant information, every word earns its place.

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

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

Given 12 parameters, nested objects, and no output schema, the description explains parameter constraints, behavior, and return shape. It does not mention error cases or prerequisites (e.g., pane existence), but is fairly complete for a complex 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 100%, so baseline is 3. The description adds semantic value by explaining mutual exclusivity of ttl_seconds/expires_at, clearing behavior via clear_* fields, and wholesale replacement of input_data. It also describes the return shape (full new state + updated_fields array).

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 verb (Edit/update), resource (a LIVE pane), and the specific behavior (in-place PATCH without minting a new one). It distinguishes from the sibling tool upgrade_pane, which swaps HTML/schemas.

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

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

The description explicitly states 'Pass at least one field' and guides the agent to use upgrade_pane for swapping HTML/schemas. However, it does not provide broader guidance on when to use this tool versus other sibling tools like create_pane or delete_pane.

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

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

Annotations already indicate mutation, destructiveness, and idempotency. The description adds behavioral context: it replaces entire data, details optimistic locking behavior including version mismatch handling and retry flow, and specifies the return format. No contradictions.

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

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

Three sentences with no wasted words. The main action is front-loaded, and critical details (optimistic locking, return value) are included efficiently. Each sentence earns its place.

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

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

For a 5-parameter destructive mutation tool with no output schema, the description covers key behaviors and return value. It lacks explicit error conditions or permission requirements, but with annotations and schema, it is largely sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema, particularly for if_match by explaining its role in optimistic locking and retry, and for data by emphasizing replacement nature. This improves parameter understanding.

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

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

The description clearly states the tool updates an existing row in a pane's record collection and replaces its data, specifying the verb and resource. It distinguishes from siblings like get_record, delete_record, and upsert_record by focusing on strict update with optimistic locking.

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

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

The description provides some guidance on when to use optimistic locking with if_match, but it lacks explicit comparison to similar tools like upsert_record. It does not state when to prefer this tool over alternatives or when not to use it, leaving the agent to infer from context.

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

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

The description discloses the tool's mutating nature (consistent with destructiveHint=true) and details behavioral traits: it appends a fresh version, re-pins in place, and has a strict schema-compat gate that returns schema_incompatible_upgrade errors unless force is used. It also describes the return object structure.

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 well-structured with a clear opening sentence, numbered usage modes, and logical flow. While every sentence adds value, it is slightly verbose; a bit more conciseness could improve readability without losing information.

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

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

Given the tool's complexity (9 parameters, nested objects, no output schema), the description sufficiently covers all essential aspects: behavior, mutation, modes, default values, error handling, and return format. It provides complete guidance 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?

All 9 parameters have descriptions in the input schema (100% coverage), and the description adds meaningful context beyond the schema, especially for the html and template_version parameters, explaining mutual exclusivity and inheritance behavior. However, not all parameters are elaborated in the description text.

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

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

The description clearly states the tool re-pins a LIVE pane to swap HTML and schemas in place while preserving URL. It distinguishes two modes (inline via html parameter, template via template_version parameter) and differentiates from siblings like update_pane and create_pane.

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

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

The description explicitly provides two usage scenarios with clear guidance on when to use each: inline panes (using html) and named/reusable templates (using template_version). It also explains mutual exclusivity, default behaviors, and the schema-compat gate with force option.

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

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

The description details the dedup behavior when record_key is reused (returns existing row), and specifies the return structure '{ record, deduped }'. Annotations already state idempotentHint=true and destructiveHint=true, and the description adds concrete context without contradiction.

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

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

The description is concise, front-loaded with the main purpose, and each sentence adds essential information. No wasted words.

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

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

For a 4-parameter tool with no output schema, the description covers purpose, usage, prerequisites, return value, and even guides to sibling tools. It is fully adequate for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that record_key enables dedup and that data must be valid against the collection schema, going beyond the schema descriptions.

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

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

The description clearly states the tool creates a row or returns an existing one if record_key is present, with 'deduped:true'. It specifies verb 'Create' and resource 'row in a pane's record collection', and distinguishes from siblings like create_record by highlighting dedup behavior.

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

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

The description gives explicit when-to-use examples ('add a todo, a line item, a comment'), prerequisites ('collection must be declared... with agent allowed to write'), and even guides to call get_skill as an alternative for design-phase decisions.

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