Quillm

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds traits annotations cannot express: it runs a real headless browser, transmits a screenshot and page text to OpenAI (an external data disclosure), and that transmission is skipped if the workspace disabled checks. This is exactly the kind of behavioral context that matters before invoking.

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

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

It is a longer description, but it is front-loaded with the core behavior, then the external-call caveat, then the parameter hint and usage routing. Every sentence carries information; only slight trimming of the output enumeration would tighten it further.

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

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

There is no output schema, so the description carries the burden of describing return values and does so thoroughly (errors, datasets loaded, missing content, optional screenshot). Combined with the usage routing and external-call disclosure, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema for screenshot: it tells the agent the flag exists so it can judge layout itself, explaining the purpose rather than just the type. The slug parameter is left to the schema, which is acceptable.

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 (test-renders a view in a real headless browser) and enumerates the concrete outputs: render errors, console errors, loaded datasets, and missing reader content. It explicitly separates itself from create_view/update_view, which run this automatically, so an agent can tell it apart from siblings without opening a schema.

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

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

Gives explicit when-to-use conditions: when you want the screenshot, after changing a dataset, or to confirm the review is clean before telling the user it is done. It also states that create_view and update_view already run this automatically, which effectively names the alternatives and when not to reach for this tool.

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

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

Annotations already declare the safety profile (not read-only, not destructive, not open-world), so the bar is lower. The description still adds real behavior: the `key` semantics and that pushing a row with an existing key updates rather than duplicates. It does not cover failure modes (duplicate name, 5000-row/60-column limits) that live only in the schema.

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

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

Front-loaded with the core purpose and the key contract, then the routing rule. Roughly five sentences, all relevant, though the tidy-data modeling advice is the one part that could be trimmed without losing invocation-critical 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, the description carries the return-side burden and adequately conveys what the created artifact is and how it is consumed. Limits (row/column caps) and duplicate-name behavior appear only in the schema, leaving a small completeness gap for a 6-parameter mutation tool.

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

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

Schema description coverage is 100%, so 3 is the baseline. The description adds meaning beyond the schema: `key` as the uniqueness/idempotency contract and a modeling preference for tidy raw-ish numeric rows over pre-aggregated text, which shapes how `columns` and `rows` should be populated.

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 ("Creates a named table") and immediately frames the artifact's role ("that views read with useDataset(name)"). It further distinguishes itself from siblings by naming get_workspace and upsert_rows for the 'dataset already exists' case.

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

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

Explicit routing: "Check get_workspace first: if a dataset with this data already exists, add to it with upsert_rows." It also gives positive guidance on when this tool is the right shape (new raw-ish data) versus pre-aggregated text.

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 safety/idempotency, and the description goes well beyond them: it discloses that the view is compiled, test-rendered in a real browser and reviewed immediately, that the response reports render status/errors/gaps, that a thin brief is refused once, and that two outside services (TypeSafe, OpenAI) process the brief and a screenshot. That external-service data exposure is exactly the kind of context annotations cannot carry.

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

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

Purpose and constraints are front-loaded and nearly every sentence carries operational content. It is long (~10 sentences) and some material (the brief, the questions ordering) duplicates the schema's own descriptions, which slightly dilutes conciseness.

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 12-parameter tool with nested objects and no output schema, the description covers what is missing from structured data: the data-binding contract for `source`, the refusal behavior, and what the response returns. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so the schema carries the parameter definitions and a baseline of 3 applies. The description still adds real meaning: `source` must be ONE file of React that default-exports a component and reads data via useDataset from 'quillm', and `questions` must be written before the source. It does not, however, add much for the many other required fields.

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

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

States a specific verb and resource ('Creates a new view') and immediately defines what a view is: 'a live page at a stable URL in the user's dashboard app.' It explicitly distinguishes itself from siblings create_dataset and update_view, so an agent can select it without opening any schema.

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

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

Gives explicit sequencing and alternatives: create the dataset first via create_dataset, call get_guide first for the template, check get_workspace first and use update_view if a suitable view already exists. When-not-to-use (existing view) and prerequisites are all spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so safety profile is covered. The description adds valuable non-annotation behavior: permanent row removal, a refusal condition involving views, and the force override. It stops short of describing the changelog side effect of the reason parameter, but for a destructive tool this is strong disclosure.

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 short sentences, front-loaded with the destructive action, then the refusal/override condition, then the usage constraint. Every sentence earns its place with 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?

For a destructive tool with no output schema and complete parameter coverage in the schema, the description supplies the missing behavioral context an agent needs: permanence, view-dependency refusal, force override, and a user-consent condition. It could mention logging to the changelog, but the essential call-safety profile is complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description clarifies force semantics and the reason requirement but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (deletes) and resource (dataset) with the scope of destruction ('and all its rows') made explicit in the first sentence. Screenshot siblings like delete_rows and delete_view are distinguishable because the resource is named precisely.

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 an explicit precondition ('Refuses if any view still reads it, unless force=true') and a usage boundary ('Only do this when the user asked for it'). It does not name an alternative tool for softer deletion, but the conditionality of the force path is well covered.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the all-vs-key mode distinction, but says nothing about irreversibility, behavior when a key does not exist, or required permissions, so it adds only modest context beyond the annotations.

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

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

A single sentence that front-loads the operation, gives an inline example, and covers the alternative mode with its use case. 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?

With full schema coverage and annotations carrying the destructive profile, the description covers both deletion modes adequately for correct invocation. It stops short of describing what happens to non-matching keys or whether deletion is reversible, which would be helpful for a destructive tool, 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?

Schema description coverage is 100%, so each parameter (all, keys, note, dataset) is already documented in the schema. The description restates the keys example and the all=true meaning without adding format, constraint, or interaction details beyond what the schema provides.

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 ('Deletes rows from a dataset') and clarifies the two deletion modes with a concrete key example. It implicitly separates itself from delete_dataset/upsert_rows via the 'rows' scope, but never names a sibling to make the boundary explicit.

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 one concrete scenario for the all=true path ('use before re-loading a dataset from scratch'), which is genuine when-to-use guidance. However it offers no guidance on when key-based deletion is preferable to upsert_rows or delete_dataset, and no exclusions or preconditions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds the useful nuance that removal is permanent and warns against unsolicited use, but says nothing about recoverability, permissions, or side effects on share_view/check_view references.

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, zero waste, with the destructive consequence front-loaded and the caution trailing it. Nothing superfluous.

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 destructive tool whose annotations already flag destructiveness and whose parameters are fully documented, the description covers purpose and the key caution. It is only slightly incomplete in not addressing permissions or whether a deleted view can be restored.

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

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

Schema description coverage is 100% and both parameters (slug, reason) are documented in the schema itself, including the changelog purpose of 'reason'. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb ('removes') and resource ('a view') with an explicit scope ('from the user's workspace'), letting an agent distinguish it from delete_dataset, delete_rows, and other delete siblings by resource alone.

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

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

'Only do this when the user asked for it' gives one usage condition, but there is no when-not guidance, no mention of the update_view alternative, and no prerequisites such as required permissions.

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, openWorldHint=false, so the safety profile is covered; the description still adds value by disclosing what the response contains and establishing the once-per-session caching expectation. It does not discuss failure modes, but for a static documentation read that is a minor gap.

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

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

Three short sentences, front-loaded with the return payload and followed by the action guidance. Every clause carries information; no filler beyond the deliberate reassurance that the guide is short.

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

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

With no output schema, the description compensates by enumerating the guide's sections, so the agent knows what it will receive. Combined with the annotations covering safety and the zero-parameter schema, nothing needed to call this tool correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter meaning is lost because none exists.

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

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

States a specific verb and resource ('Returns the complete how-to for Quillm') and then enumerates the actual contents (view code contract, template, importable libraries, styling rules, dataset conventions). An agent immediately knows this is the documentation primer, not a data or view operation, which separates it cleanly from siblings like get_view or create_view.

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

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

Gives explicit when-to-use guidance with both timing and downstream dependency: 'Read this once per session before you call create_view or update_view.' It names the sibling tools it gates and even addresses the cost concern with 'It is short,' removing any reason to skip it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds meaningful return-shape context (the full manifest including source code) that no output schema supplies, though it says nothing about size/cost of fetching full source.

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

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

Two sentences, zero filler, and the return contents are front-loaded before the call-ordering directive. Every sentence earns its place.

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

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

With no output schema, the description carries the burden of describing return values and does so concretely (metadata, notes, revision history, dataset schemas, source). Combined with annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so slug, revision, and include_source are already fully documented in the schema. The description's phrase 'in full' and mention of 'revision history' only loosely gesture at include_source/revision, adding little beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb ('Returns') and resource ('one view in full') and enumerates exactly what comes back: metadata, notes, revision history, dataset schemas, and React source. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like check_view or get_workspace.

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?

'Always call this before update_view so your edits match the current source exactly' gives an explicit trigger condition and names the alternative workflow it feeds into. An agent knows precisely when this tool is required rather than optional.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context: the response is a 'compact overview' and enumerates the categories returned (views with slug/purpose/datasets/URL/last editor, datasets with columns/key/row count/freshness, notes, recent changes). It does not mention auth requirements or size/pagination 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?

Front-loaded with 'START HERE', followed by one dense sentence enumerating contents and a closing call-to-action. Every clause earns its place and there is no filler.

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

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

No output schema exists, so the description carries the full burden of describing return values — and it does so in detail across all four content categories. Combined with annotations covering safety, an agent has everything needed to call and interpret this 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing to disambiguate and the description correctly implies a no-argument call.

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

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

States a specific verb+resource ('Returns everything that exists in the user's Quillm workspace') with an enumerated scope of what that includes (views, datasets, notes, recent changes). It is clearly distinguishable from siblings like get_view or check_view, which cover single entities.

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

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

Explicitly prescribes when to call it ('START HERE', 'Call this at the start of every task') and states the rationale/alternative behavior (extend what exists instead of duplicating). The agent knows both the trigger condition and the consequence of skipping it.

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

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

Annotations declare only the safety profile (readOnly/idempotent/non-destructive); the description adds the behavior that matters here: platform-dependent rendering, mandatory last-call ordering, and the fact that the mutation siblings produce no visible chat output. Nothing contradicts the annotations, and the added context goes well beyond them.

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, no filler, front-loaded with what the tool does before the calling conditions. Every clause carries distinct information (rendering modes, call ordering, sibling behavior, slug semantics).

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

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

There is no output schema, but the description explains both possible return shapes (inline page vs link), the single optional parameter's effect, and the ordering constraint. Everything an agent needs to invoke this correctly 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 description coverage is 100% and already states the slug may be a page URL and that omission lists everything, so the description's 'Without a slug, lists every page' largely restates the schema. Baseline 3 is appropriate for a single fully documented optional parameter.

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 and resource ('Shows the user a page inside the chat, live, with today's data') and immediately distinguishes the two runtime modes: inline rendering in ChatGPT/Claude versus returning a link elsewhere. An agent can separate this from get_view or create_view without opening any schema.

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

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

Gives explicit timing ('Call it once, last...after the review is clean') and trigger ('when the user asks to see, open or show a page'), and names the siblings it complements rather than replaces ('create_view, update_view and upsert_rows show nothing in the chat themselves'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already establish the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds useful capability context beyond them: simple filters, ordering, paging, and the fact that the response includes the total row count.

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 verb and resource, with no redundant restatement of the title or schema. Every clause adds information about capability or output.

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?

Read-only tool with full parameter documentation, complete annotations, and no output schema; the description compensates by noting the total row count in the response. Nothing essential for correct invocation 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 100%, so every parameter (limit, where, offset, order_by, descending, dataset) is already documented with defaults and operator syntax. The description only gestures at 'simple filters, ordering and paging' without adding syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reads rows from a dataset') and adds the intent ('inspect or analyse what is stored') with a concrete example. This clearly separates it from write-oriented siblings like upsert_rows and delete_rows, though it never names an alternative explicitly.

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

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

Provides a clear usage context in the parenthetical example ('to see the latest month before adding the next one'), which tells the agent when this read tool is appropriate. It lacks any explicit when-not guidance or routing to sibling tools such as get_view or check_view.

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 mark this as a non-readonly, open-world, non-idempotent write, and the description adds real behavioral context beyond that: the note leaves the user's workspace to an external person, so no private data may be included; one call per distinct problem; and the agent must still complete the task and inform the user. These are disclosure obligations an agent could not infer from the structured fields.

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

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

Front-loaded with the purpose, then the when-to-call criteria, then the exclusions. It is dense but nearly every clause carries routing or compliance value; the long parenthetical defining 'workaround' is justified by how easily that category is misjudged, though the paragraph is longer than strictly necessary.

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

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

There is no output schema, and none is needed for a fire-and-forget report tool. Purpose, triggers, exclusions, timing, cardinality, privacy constraints, and the obligation to finish the user's task are all covered, leaving no gap an agent would need to guess at.

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%, including per-enum-value documentation for 'kind', so the schema already carries the parameter burden. The description adds only an indirect constraint (nothing private goes into the fields) and does not clarify any individual field's expected content. 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 first sentence states a concrete verb and target ('Files a note for Quillm's maintainer') and scopes it to product shortcomings rather than user data, which cleanly separates it from the sibling write_notes tool. An agent knows exactly what artifact is produced and who receives it 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 enumerates explicit trigger conditions (missing capability, workaround, confusing error or guide, missing library) with an operational definition of 'workaround', and explicitly excludes cases ('Do NOT use it for problems with the user's data or request, for your own coding mistakes..., or for praise'). It also gives timing guidance (file as soon as recognised, before follow-up questions) and cardinality (one call per distinct problem).

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is partly structured. The description adds real context beyond that: 'link' makes the page and its data readable by anyone, is read-only, and is embeddable, and it states the tool returns the link. It does not discuss revocation or what happens to existing links.

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

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

Front-loads the core behavior and the level meanings, then the usage condition, then the caution — a sensible order. It is somewhat long because the enum values are restated from the schema, but no sentence is pure filler.

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

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

For a 2-param mutation tool with no output schema, the description covers purpose, usage constraint, side effects, and the return value ('Returns the link'). The only gap is what happens on re-share or revocation and whether the returned link format is described, which is minor.

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

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

Schema description coverage is 100% and the enum for 'level' is fully documented in the schema, including the semantics of each value. The description largely mirrors that enum text, so it adds little 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?

Names a specific verb+resource ('changes who can open a page') and enumerates the three levels it can set, so an agent can distinguish it from siblings like update_view or open_page. The effect on the page's audience is stated concretely rather than restated from the title.

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 ('when the user asks you to share a page or to give them a link to send') and an explicit guardrail ('Only when the user asked'), which is a when-not condition. Nothing about selection has to be inferred.

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, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: existing rows keep their values, new columns are null until upserted, and a type change is validated against every existing row first.

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

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

Front-loaded with the core operation, then consequences, then the key constraint; sentences are dense but each carries information. The 'Keep descriptions true' sentence is slightly tangential but serves as actionable guidance rather than filler.

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

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

For a destructive 7-parameter mutation tool with no output schema and full annotation coverage, the description supplies the data-preservation semantics an agent needs to act safely. It stops short of describing ordering when multiple mutation fields are passed together, which is a minor gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by mapping intents to parameters (type/description fixes go through update_columns) and by stating a constraint absent from the schema — that the dataset key is immutable. It still does not disambiguate add_columns versus update_columns when a column exists but is being retyped.

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 and enumerates the exact mutation categories (add/remove columns, update column description or type, change dataset description or cadence), which clearly separates it from create_dataset and delete_dataset. An agent can tell what this tool does without opening the schema.

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

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

It routes the agent for one important case — 'The key cannot be changed; create a new dataset for that' — and implicitly points at upsert_rows by noting new columns stay null until values are upserted. It does not, however, explicitly state when to prefer this over upsert_rows or create_dataset in general.

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

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

Goes well beyond the annotations: every call creates a new revision, is test-rendered and reviewed, a failed render is NOT published so readers keep the last working version, the review sends a screenshot and page text to OpenAI unless checks are off, and stale revisions block the save. These are consequential behaviors (privacy, failure mode, concurrency) an agent could not infer from the structured fields.

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

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

Front-loaded with purpose and the concurrency contract, and each sentence carries operational weight. It is on the long side for a description and repeats the get_view prerequisite twice, but there is little filler.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the failure mode, revision safety net, external data disclosure, prerequisites, and the alternative tool for a common adjacent intent. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds comparative semantics beyond it, explaining that edits are exact unique string replacements like find-and-replace, that source must not be combined with edits, and how expected_revision guards against overwriting another agent's change. It stops short of covering the other 11 parameters, which the schema already documents well.

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 ('Changes an existing view's code or metadata') and immediately contrasts with siblings: get_view for reading, upsert_rows for changing only numbers. An agent can distinguish this from create_view, delete_view, and update_dataset without opening a schema.

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

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

Explicit routing: prefer `edits` for targeted changes, use `source` only for full rewrites, `restore_revision` to roll back, and a named when-NOT-to-use ('do NOT use this tool: use upsert_rows on the dataset'). It also states the prerequisite ('Call get_view first to get the current source').

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

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

Goes well beyond the annotations: it discloses the key-based match/insert-vs-merge rule, that only supplied columns are overwritten, that views update immediately without edits, and that writes are confined to this workspace with no external calls. These details materially inform a destructive, idempotent mutation that annotations alone could not convey.

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

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

Front-loads the core behavior, then layers matching, idempotency, typing rules, and scope in a tight sequence. Every sentence carries actionable information with no filler.

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

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

For a 3-param mutation tool with no output schema, the description covers matching, typing, null conventions, and side effects well. It does not indicate what the call returns (e.g. inserted/updated counts) or any size/rate caveats around the 5000-row cap, leaving a minor gap.

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

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

Schema coverage is already 100%, but the description adds real semantics the schema lacks: how rows are matched on key columns, the required key column inclusion, and strict value typing rules (JSON numbers not "$1,200", ISO dates, null instead of "" or 0). This is substantive value beyond the schema 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?

States a specific verb+resource ("Adds or updates rows in a dataset") and immediately clarifies intent with the aliases "add new data" / "correct a number". This clearly separates it from delete_rows, query_dataset, and create_dataset in the sibling list.

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

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

Explains when to reach for it (adding data, correcting values) and that matched keys merge rather than duplicate, which guides invocation. It never names the sibling alternative (e.g. delete_rows for removal) or states when not to use it, so it stops short of full routing guidance.

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

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

Annotations flag destructiveHint=true and idempotentHint=true; the description earns credit by making the destruction explicit and actionable — 'Replaces the previous notes for that target, so include what should be kept.' It also discloses where notes surface (get_workspace / get_view), which annotations cannot convey.

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

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

Front-loads purpose, then usage examples, then the replacement warning — all three sentences carry distinct value. The parenthetical examples are longer than strictly necessary but aid correct invocation.

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

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

For a 3-parameter mutation with no output schema, the description covers what the tool does, what content belongs in it, what gets destroyed, and where the result is visible. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents target_type enum, the workspace-omission default, and the replacement behavior. The description's mapping of notes to view/dataset/workspace largely restates the enum, adding 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?

States a specific verb and resource ('saves durable notes') and explains the exact niche it fills: persistent memory across sessions. An agent can distinguish it from all siblings such as create_view or report_feedback without opening another schema.

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

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

Gives concrete inclusion criteria with examples (data provenance, definitions like 'MRR excludes one-off invoices', user preferences) and warns that notes replace prior content so everything to be kept should be included. No alternatives or explicit when-not-to-use are named, so it falls short of a 5.

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