Pizza Developer

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

Goes well beyond the annotations (which only say non-readOnly, non-destructive, idempotent, open-world) by disclosing per-kind side effects: what surfaces the record disappears from, what content/revision history survives, and that an in-flight workflow run continues while new runs are blocked. The reversible-via-unarchive behavior is consistent with destructiveHint=false.

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

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

Front-loaded with a one-sentence summary and the reversibility guarantee before the per-kind bullets. The length is justified because archiving genuinely differs per kind, though seven bullets is a lot to absorb.

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

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

For a mutation tool with no output schema, it covers reversibility, retained content, and visibility changes for every supported kind. It omits error/permission cases (e.g. what happens if the id does not exist or the record is already archived) and does not describe the response.

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 real meaning by unpacking each of the seven kind enum values into concrete per-kind behavior. The id parameter is covered only generically, keeping this from a 5.

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

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

States a specific verb (archive) and resource (one record, keyed by kind and id), plus the core behavioral promise: it leaves the active list but keeps its content, and unarchive reverses it. This clearly separates it from the delete_* siblings and from unarchive.

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?

Strong implied guidance: archiving is the reversible alternative to deletion, and multiple bullets note that 'only archived X can be deleted', which tells the agent archive is a prerequisite step. It lacks an explicit when-not-to-use or direct naming of the delete siblings, so it stops short of a 5.

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

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

Annotations already set readOnlyHint=false and destructiveHint=false, and the description adds real behavioral detail beyond them: it claims/consumes Work, may auto-start the next planned batch, and returns the Work brief plus the project's own instruction documents. The disclosed implicit side effect (automatic batch start) is the kind of trait 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?

Four tight sentences, front-loaded with the core action before the claiming/run details. Some jargon ('boundary call', 'developing there', 'implementable work') is slightly opaque but overall efficient with little waste.

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

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

For a mutation tool with no output schema and all parameters described, the description covers invocation paths and even what is returned (brief + instruction documents). It does not mention permissions/auth requirements or failure behavior, a minor gap given the annotations already cover the safety profile.

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), but the description adds meaning beyond the schema field blurbs: projectId specifically resumes the active Work or claims the next ordered one, and runId only matters when several runs are open. This relationship logic is not present in 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?

States a specific verb+resource: 'Begin repository implementation' by claiming, resuming, или kicking off a Work/Batch. The mechanics (claim by workId, resume/claim-next by projectId) distinguish it clearly from siblings like create_work, get_work, and finish_work, though it never names an alternative tool 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?

Explains request intent well: pass workId to claim, projectId to resume/claim the next ordered Work, runId when multiple runs are open. This tells the agent when each path applies. It lacks explicit 'use X instead' routing against siblings such as get_work or resume_workflow, so it stops short of a 5.

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

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

Annotations already carry the destructive profile (destructiveHint=true, readOnlyHint=false), so the bar is lower; the description still adds real value by scoping what is NOT destroyed (recorded route and measurements survive) and what the caller must supply (a truthful reason). It stops short of saying whether cancellation is reversible or who may cancel.

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

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

Two tight sentences with zero filler, and the key differentiator (preservation of route/measurements) is front-loaded before the input requirement. Nothing could be cut without losing information.

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

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

For a two-parameter mutation with no output schema and full annotation coverage, the description supplies the essential contract: what gets cancelled, what survives, and that a reason is mandatory. It omits post-cancellation state and any permission requirement, but nothing critical 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% with only two parameters, so the schema already documents runId and reason fully. The description only echoes the reason requirement with added emphasis on truthfulness, adding little beyond the structured fields; 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?

States a specific verb (Cancel) and resource (workflow run) with an explicit scope qualifier: only an open run, and the route/measurements are preserved. That implicitly separates it from delete_workflow and resume_workflow, though no sibling is named outright, so it falls just short of the top band.

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

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

The phrase 'open workflow run' implies the precondition that the run must still be in progress, and 'A truthful reason is required' signals a mandatory input. But there is no explicit when-to-use vs. when-not guidance and no pointer to delete_workflow for permanent removal, so usage must 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?

Goes well beyond the readOnly/openWorld annotations: it discloses that checking is done by TypeSafe, exactly what data is transmitted and what is explicitly never sent (account name, email, identifier), the 0.75 pass threshold, and that unchanged records reuse earlier verdicts. This is unusually rich behavioral context.

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 dense with useful detail; every sentence (privacy disclosure, kind constraint, id override, return values, saved-verdict reuse) earns its place. It is a single long paragraph that would read better with structure, which keeps it from a 5.

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

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

With no output schema, the description carries the full burden of the return shape and does so: passed/failed rules with probability, unchecked rules with reasons, and the sentToTypeSafe/fromSavedVerdicts counts. Combined with the workflow and kind constraints, an agent has what it needs 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% (baseline 3), but the description adds real semantics: record.kind must match the kind of write checked by that step's connection, and passing a record id starts from the saved record while any supplied fields override it. That clarifies the id-vs-fields interaction the schema does not.

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

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

States a specific verb and resource ('Check a draft against the rulesets') and immediately scopes it ('on the current step of an open workflow run, without saving it and without refusing'). This clearly distinguishes it from write siblings like update_rule, create_rule, or list_rulesets.

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 strong conditions: rules run only inside workflow runs, runId names the run, and record.kind must match the kind the step's connection checks. It also notes batch recheck limits ('only until one of its Works is done'). It stops short of naming an explicit alternative for a non-workflow check, but the 'without saving' framing effectively separates it from update 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 give the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds real behavioral detail: the batch takes the next sequential number and queue position, works start planned in the order given, the result carries batch-scoped references like `4-1`, and the call can complete a workflow planning step. It doesn't disclose retry/idempotency behavior in prose, but requestId is covered 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?

The purpose leads, followed by naming rules, resulting behavior, and workflow interactions, so it is well front-loaded. It is dense and the final sentence packs multiple workflow conditions, but each sentence carries distinct 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 explains what the call returns (batch-scoped work references ready for commit messages), the numbering/queue side effects, and the workflow-step and edgeId interactions. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: edgeId 'can name the Batch stage route so no separate resume_workflow call is needed' and works are created 'in the order given' with resulting batch-scoped refs. The name format is restated from the schema pattern rather than extended, so it is not a 5.

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

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

States a specific verb and resource ('Create a planned batch and its planned works in one call') and immediately distinguishes itself from the sibling create_work, which the description says adds a Work to an existing Batch. An agent can tell the two apart without opening either schema.

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

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

Explicitly frames this as 'the normal way to plan a batch once its scope is agreed' and names the alternative (create_work) with its distinct use case. It adds conditional guidance for runId when multiple runs wait on a Batch and for edgeId to avoid a separate resume_workflow call.

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 it as a non-destructive, open-world write, and the description goes well beyond that: it explains workflow-stage completion semantics ('completes the run's Delivery stage'), that a batch-less delivery never completes that stage, the refusal behavior, and the backfill mode. It doesn't cover post-creation visibility/permissions of the public page, but the mutation semantics are richly disclosed.

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

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

Purpose is front-loaded and each sentence carries a distinct rule (backfill, default ship-now, stage completion, refusal). It is dense with long, clause-heavy sentences that could be split for readability, but little is padding.

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 seven-parameter mutation with nested metrics and no output schema, the description supplies the conditional behaviors that determine correctness: stage-completion coupling with workflows, the refusal case, and backfill semantics. Nothing essential to a correct call 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 the baseline is 3, but the description adds real meaning beyond the schema: name is a free-form label (release number common but optional), summary must be factual, and critically the shippedAt/batchIds interaction (omit batchIds + pass real past shippedAt for pre-toolship releases). metrics and requestId are left entirely to the schema.

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

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

Opens with a specific verb+resource+scope: 'Create a shipped public delivery from selected undelivered batches.' It is immediately distinguishable from siblings like update_delivery, delete_delivery, create_batch_plan, and start_workflow, and clarifies that batches must be undelivered and unclaimed by another delivery.

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 names explicit modes and exclusions: normal creation from batchIds, the historical-backfill path (omit batchIds and pass shippedAt), the default 'ships now' behavior, and the refusal condition when the project has a Delivery-starting workflow and the call is made outside a run. An agent can pick the right invocation path without inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful scope qualifier 'project-scoped' but says nothing about duplicate-word behavior, conflict handling, or the idempotent-retry behavior (that detail is carried entirely by the schema's requestId).

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

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

A single tight sentence with the verb and scope front-loaded and no filler. The trailing field list ('a word, its aliases, and its definition') largely restates the schema properties, which slightly dilutes the value of the sentence but costs little.

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 five-parameter create tool with full schema coverage, annotations, and no output schema, the definition is nearly sufficient. The remaining gap is behavioral: uniqueness/conflict semantics for the dictionary term are not stated anywhere an agent would look before calling.

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 word, aliases, definition, projectId and requestId are all documented in the schema itself. The description echoes three of the five field names without adding format, constraint, or interaction detail beyond what the schema already states, 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?

Names a specific verb (Create), a specific resource (dictionary term), its scope (project-scoped), and the payload fields it carries (word, aliases, definition). An agent can tell it apart from update_dictionary_term, but the description does not distinguish it from the many other create_* siblings (create_rule, create_info), relying on the resource name alone to do that work.

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

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

Usage is only implied: an agent infers it should call this when it needs a new project glossary term. There is no explicit when-to-use statement, no mention of the update_dictionary_term alternative, and no note about preconditions such as whether the word must be unique within the project.

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

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

Annotations cover the safety profile (not readOnly, not destructive, closed-world), so the description only needs to add context. It does: newly created ideas land at the back of the ordering, and a title colliding with a declined idea is rejected. Auth requirements and side effects on existing ideas are unstated, keeping it at 4.

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

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

Four tight sentences with the core action and constraint front-loaded and no filler. Minor redundancy in restating the 20-character title limit already in the schema keeps it from a 5.

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

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

With no output schema, the description carries more of the burden, and it does not state what is returned on success. It otherwise covers constraints, optionality, ordering behavior, and a failure case adequately for a 6-parameter create 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 goes beyond the schema by clarifying that impact is product scope rather than priority, and that summary/content are optional and never auto-generated — real semantic additions the schema does not convey.

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

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

States a specific verb and resource ('Create a project idea') and adds distinguishing behavior — declined-name refusal and back-of-order placement — that separates it from update_idea/get_idea. It does not explicitly contrast with the update/restore siblings, so it falls short of a full 5.

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

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

Provides one routing hint ('move it forward with reorder') and one precondition ('A name matching a declined idea is refused'), which is useful context. However there is no explicit when-to-use guidance versus update_idea or restore_idea, so usage is only implied.

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 supply the generic readOnlyHint=false / destructiveHint=false / openWorldHint=false profile, so the description must add real behavior and it does: titles are unique within the project, Info is never attached to a workflow connection, and it can change at any stage of a run. It omits what happens on a duplicate title and any permission requirements, keeping it below 5.

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

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

Front-loaded with the verb and resource, then the disambiguation sentence. It is slightly long and the 'such as where it is listed, how its marketing is done...' list is illustrative filler, but each sentence carries a distinct constraint (uniqueness, currency, lifecycle, instruction redirect).

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 create tool with no output schema and only generic annotations, the description covers what the resource is, uniqueness, lifecycle, and the sibling boundary. The remaining gap is the failure mode for a duplicate title and what the create returns, which the agent would have to discover empirically.

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 all five parameters (including requestId's idempotent-retry semantics and the unique-title constraint) are already documented in the schema. The description reinforces uniqueness for title but adds no format, syntax, or validation detail beyond that 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?

States a specific verb (Create) and resource (Info page) and then defines the resource by example: 'a titled page of facts about the project that are not rules or features'. It also carves out the boundary against the sibling concept, telling the agent that rules for how to work belong in an instruction, so create_instruction vs create_info is separable without opening schemas.

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

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

Gives clear context for use (facts about listing, marketing, outside accounts) and an explicit redirect for the adjacent case ('Rules for how to work belong in an instruction instead'). It also names update_info for keeping the page current. It stops short of stating exclusions like when an idea, rule, or feature should be created instead, so it is short of a 5.

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

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

Annotations declare a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds meaningful behavior beyond that: title uniqueness within the project, the workflow-stage gating rule, and the returned id. It does not say what happens on a duplicate title (error vs. merge) or whether the create is idempotent, leaving some behavioral gaps.

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

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

Four compact sentences, front-loaded with the core action and followed by constraints and the return pointer. Little waste; each sentence carries distinct information, though the phrasing is slightly terse.

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 compensates by stating what is returned (its id) and how it is used (for update_instruction). Combined with 100% schema coverage and explicit annotations, the definition is sufficient to call the tool correctly; only duplicate-title and idempotency behavior are left unstated.

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 four parameters including the requestId retry semantics. The description only loosely restates title ("freely titled") and content ("full text when known") without adding format or constraint detail, so 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?

States a specific verb and resource ("Create an instruction document on a project") and adds a differentiator ("freely titled (there is no fixed set)") that separates it from structured-schema siblings like create_dictionary_term or create_rule. It does not name any sibling directly, but an agent can identify the operation 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?

Provides one real usage constraint — during an active workflow run, instruction changes are accepted only in its self-improvement stage — and points to the follow-up tool (update_instruction) via the returned id. It never states when to choose create_instruction over create_info or similar document-creating siblings, so guidance is partial and implied rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavior: Ideas are order-preserving, only the first two become planning input, and 'everything is validated before anything is written' discloses atomic all-or-nothing semantics.

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 the core action and the required-vs-optional split. Dense with useful behavior and no filler, though the list of later-addable entities is slightly long.

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 create tool with annotations covering safety and no output schema, the description covers required fields, optional additions, validation behavior and the special semantics of ideas. The requestId retry behavior is documented in the schema, so nothing critical 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 goes beyond the terse schema descriptions by explaining that Ideas retain order and that up to the first two feed planning input, clarifying the semantic role of the ideas parameter rather than just restating it.

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

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

States a specific verb+resource ('Create a project') and clarifies that supplied Ideas come along, so the agent knows this is the project-creation entry point with optional nested ideas. It does not explicitly contrast with siblings like create_idea or create_work, but the scope is unambiguous.

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

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

It tells the agent only the name is required and that Ideas, Batches, Works, Deliveries, a Workflow, repo and live URL can be added later, which implies the minimal call. However it offers no explicit when-to-use-vs-alternative guidance (e.g. create this vs create_idea standalone).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine runtime context the annotations cannot convey: rules are evaluated only during workflow runs, and the judge receives the connection's Dictionary and Features plus the run's Idea. It stops short of describing validation failures, effect on in-flight runs, or permissions.

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, purpose front-loaded before the runtime explanation. The second sentence is dense and slightly convoluted ('where the judge is given ... automatically') but every clause carries information 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 mutation tool with no output schema and four fully documented parameters, the description covers what is created, where it lands, its default severity, and when it is enforced. It could say more about failure behavior and whether new rules affect existing runs, but nothing essential for a correct call 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 the baseline is 3. The description goes one step further by stating that 'must' is the default level, a fact the schema does not encode (the enum lists both values with no default). Its 'one narrow statement' phrasing duplicates the schema's wording for text, adding nothing there.

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

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

States a specific verb and resource ('Add a rule') plus placement semantics ('to the end of a ruleset'), which cleanly separates it from update_rule, delete_rule, and create_ruleset. It also notes the default level, so an agent knows the shape of the created record 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 supplies meaningful usage context ('Rules run only inside workflow runs') which tells the agent when rules actually take effect. However, it never routes the agent between alternatives (update_rule for edits, create_ruleset for containers) and gives no explicit when-not-to-use condition, so guidance remains implied rather than explicit.

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

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

Annotations already indicate a non-read-only, non-destructive, closed-world mutation. The description adds valuable behavioral context: rules run only inside workflow runs and are checked when a ruleset is attached to a workflow connection and the step's write occurs. It does not cover auth requirements, rate limits, or response behavior, but the workflow-trigger disclosure is meaningful.

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 front-loaded with the core action and then adds two concise sentences of operational context. The final sentence is somewhat dense but still earns its place by explaining the workflow-run trigger.

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

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

For a mutation tool with a rich 100%-covered schema and clear annotations, the description is largely complete. It covers creation, rule phrasing, and workflow-run behavior; the absence of explicit return-value discussion is acceptable since no output schema exists, though mentioning the created ruleset would have improved completeness.

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

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

Schema coverage is 100%, so parameters are already well documented in the schema. The description names projectId/requestId only indirectly and largely repeats the schema's explanation of rule text as a narrow statement, adding no major semantic detail beyond what structured fields provide.

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 specific verb and resource: creating a ruleset with a name and optional rules. It distinguishes the tool from create_rule by focusing on a ruleset rather than a single rule, but does not explicitly name or contrast itself with siblings like create_rule or update_ruleset.

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 rules actually run (inside workflow runs, when attached via rulesetIds in update_workflow), which implies the tool's broader context. However, it does not give explicit guidance on when to call create_ruleset versus alternatives such as create_rule, update_ruleset, or update_workflow.

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 a non-destructive write. The description adds substantial beyond-annotation detail: the created Work starts in 'planned' state, begin_work transitions it, and workflow-run ruleset validation can refuse the write. This is rich, actionable behavioral context.

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?

Efficient and front-loaded: creation is stated first, then state lifecycle, then validation rules. Two sentences, 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?

Given annotations cover safety and schema covers parameters, the description completes the picture with lifecycle and validation context. It is sufficient for an agent to call correctly, though it could more explicitly route away from sibling tools.

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 schema documents all parameters thoroughly. The description does not add further parameter semantics beyond what the schema provides. Baseline 3 is appropriate when 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?

Clearly states it creates a Work in a Batch, and adds useful nuance ('that is not ready', 'always starts planned'). However, it does not explicitly differentiate from the sibling begin_work or update_work beyond mentioning begin_work starts it.

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

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

Implies usage by mentioning begin_work as the follow-up step, but does not explicitly state when to use create_work vs. alternatives like update_work or search_works. Usage context is inferred rather than stated.

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

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

Annotations only tell the agent this is a non-read, non-destructive write. The description goes well beyond that, disclosing what gets created, the semantics of omitted fields ('leaving it out attaches none'), and how context is materialized ('each adds only a short outline... that the agent expands with the read tools'). This is rich behavioral context the annotations cannot supply.

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 organized from general concept to node kinds to edge rules. Dense but every sentence carries structural information; a few long compound sentences could be trimmed, but nothing is filler.

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

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

For a complex graph-construction tool with no output schema, the description covers the valid stage topologies, required edge payloads, and prohibitions thoroughly. It does not describe the return value or idempotency behavior (left to the schema's requestId), but the calling contract is otherwise 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 the baseline is 3. The description nonetheless adds semantic depth, explaining that edge.data must carry instructionDocumentIds and contextKinds, that rulesetIds is an ordered per-connection list, and that contextKinds only add outlines — meaning beyond the terse 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 ('Create a named workflow') and immediately defines what a workflow is ('a route of stages that requests in the project follow'), so an agent understands the artifact rather than just the operation. The detail on node kinds and edge contents further distinguishes it from generic create_* siblings.

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

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

Provides strong construction guidance ('do not create Instructions, Dictionary, or Features nodes', 'Select documents on connections') and notes that 'Projects work without a Workflow', implying optionality. However, it never states when to reach for this versus update_workflow/start_workflow or list_workflows, leaving the tool-selection decision implicit.

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

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered. The description adds real state-transition detail beyond the annotations: the idea leaves the planning order, is listed among declined ideas, and a repeat decline overwrites the reason rather than failing. That is exactly the kind of context annotations cannot express.

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

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

Three short sentences, front-loaded with the core action and then the consequences. Each sentence contributes something (action, post-state, repeat behavior) 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?

With no output schema and only two well-documented parameters, the description covers what an agent needs: what the call does, what happens to the idea, and how repeats behave. It does not mention any return value or error condition, but nothing critical is missing for a small 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% (both id and reason are documented, including the max length and 'in their own words' phrasing), so the schema already carries the parameter meaning. The description's mention of the reason adds no syntax or format detail beyond it, making 3 the correct 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?

States a specific verb (decline) and resource (idea), and goes beyond the name by describing the resulting state: the idea leaves the planning order and appears with declined ideas. It does not explicitly contrast with delete_idea, archive_idea, or restore_idea, so the sibling boundary is only implied by the state-change 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?

It gives context for the action ('the vibe coder decided against') and notes that re-declining replaces the previous reason, which is useful behavioral guidance. However it never says when to prefer decline over delete_idea or archive_idea, leaving the agent to infer the choice from sibling names.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the blocking rule about batches containing works, which is useful context. It omits whether the deletion is permanent/reversible and what happens to dependent works or deliveries.

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, verb first, then the precondition. No filler, no restatement of the title, and every sentence carries a distinct fact.

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 single-parameter delete with annotations covering safety, the description is nearly sufficient. The main gap is the absence of routing to revert_batch as the non-destructive alternative and any statement about permanence of the deletion.

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?

Only one parameter (id) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or constraint detail about the id 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+resource ("Delete a batch") with a clear precondition. It doesn't differentiate itself from the sibling revert_batch, which is a non-destructive alternative for batches, so sibling routing is left to inference.

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 precondition "Batches that still have works can't be deleted" is a real usage constraint that prevents wasted calls. However, there is no guidance on when to delete versus revert an existing batch, nor on whether the id must first be archived or in a particular state.

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, but the description adds genuinely new behavioral detail beyond that: batches are unassigned (not deleted), the release presentation is deleted, and shipped deliveries rewrite public history. It also explains the confirmName safety mechanism and the idempotency-relevant archive alternative.

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

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

Dense but front-loaded: the core action and its key side effect come first, followed by confirmation mechanics and the archive alternative. Every sentence carries information, though it packs several distinct facts into a single paragraph.

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 the mutation's consequences, the confirmName requirement, and the archive alternative. Missing an explicit statement about reversibility or permissions, but for a delete tool with full annotation coverage this is notably 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 the baseline is 3. The description adds real value by clarifying that confirmName must equal the delivery's exact name – 'the free-form label it was created with' – which goes beyond the schema's terse 'to confirm deletion' 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?

Opens with a specific verb+resource and immediately clarifies the crucial side-effect (batches are unassigned, not deleted), which distinguishes this from a naive destructive delete. An agent can tell exactly what this does versus siblings like delete_batch or archive.

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 names the alternative ('archive with kind delivery hides a delivery and keeps it'), giving the agent a clear when-to-use-this vs when-to-use-that decision. The confirmName requirement is also stated as a precondition.

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 mutation/safety profile is covered. The description adds genuine value beyond that: the observable consequence (the Public Delivery Page shows none) and the reversibility guarantee (restorable from presentation history). It stops short of stating failure behavior when no presentation exists.

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

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

Two tight sentences, with the primary effect front-loaded and the reversibility note second. No filler, no restatement of the title.

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

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

For a single-param destructive tool with annotations and no output schema, the description covers what is destroyed and that it is recoverable, which is the key context an agent needs. Edge cases like deleting when no presentation exists are unaddressed, keeping it just under a 5.

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?

Only one parameter (id) exists and schema coverage is 100%, so the schema already documents it fully. The description adds no extra meaning about the id beyond 'delivery', making the baseline 3 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?

States a specific verb (delete) and a precisely scoped resource (a delivery's current release presentation), and distinguishes itself from delete_delivery (which removes the delivery itself) by targeting only the presentation. An agent can tell exactly what is removed 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?

The description conveys intent (remove the current release presentation) but never states when to choose this over update_delivery_presentation or get_delivery_presentation, nor any prerequisite such as the delivery actually having a presentation. Usage is implied rather than specified.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the genuinely non-obvious behavioral rule that only archived terms are deletable and that the delete is permanent, which the 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?

Two short sentences, no filler, with the permanence and the archive precondition front-loaded. Every clause 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 single-parameter destructive tool with no output schema, the description supplies the one thing the structured data omits: the archive prerequisite and irreversibility. It could note what happens on failure or whether deletion cascades, but nothing essential to calling 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?

One required 'id' parameter with 100% schema description coverage, so the schema already carries parameter meaning. The description adds nothing about the id format or lookup, which is acceptable and matches the baseline of 3.

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 (delete) plus resource (dictionary term) and the scope qualifier 'archived'. It cleanly separates itself from the sibling archive_dictionary_term by making clear deletion is the terminal, archive-then-delete operation.

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

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

'Active terms must be archived first' is an explicit precondition that routes the agent to archive_dictionary_term before retrying. It stops short of naming that sibling directly, but the when-to-use condition is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds the crucial nuance that the deletion is permanent (no undo) and is gated on idea state. It still doesn't mention cascade effects on related records or permission requirements, so it falls short of fully supplementing the structured safety hints.

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, no filler, with the permanent-delete semantics and the state precondition front-loaded. Every clause 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 one-parameter, no-output-schema mutation, the description covers permanence and the state gate, and the annotations cover the safety profile. Minor gaps remain around post-deletion behavior and permissions, but an agent has enough 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?

Only one parameter, fully described in the schema (100% coverage: 'Id of the Idea'). The description adds no format, sourcing, or validity constraints beyond what the schema already says, 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?

Specific verb ('delete') plus resource ('idea'), with the additional qualifier 'permanently' that separates it from archive_idea and decline_idea. It stops short of naming the siblings it supersedes, so an agent still has to infer the workflow relationship from the precondition 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?

Explicitly states the eligibility gate ('archived or declined') and the prerequisite ('Active ideas must be archived or declined first'), which effectively routes the agent to archive_idea or decline_idea as a prior step. It does not name those alternatives or state what to do instead for an active idea beyond the ordering constraint.

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, but the description adds real value beyond them: deletion is permanent, it also destroys the revision history, and there is a precondition state. It does not mention any confirmation flow or whether the id must reference an existing archived page, which 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?

Two short sentences, zero filler, with the irreversible nature and the archive precondition front-loaded before any optional detail.

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

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

For a single-parameter destructive tool with no output schema, the description covers the essential facts an agent needs: permanence, scope inclusion (revision history), and the required prior state. Missing only failure-mode details, which the annotations partially signal.

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?

Only one parameter and schema coverage is 100%, so the schema already documents "id" fully; the description adds no format, type, or lookup detail beyond it. Baseline 3 for a fully documented schema.

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

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

States a specific verb and resource ("Permanently delete an archived Info page") with the scope qualifier "archived" that separates it from the sibling archive_info/unarchive_info/delete_* tools. The added clause about revision history makes the effect 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?

Explicitly states the prerequisite: "Active pages must be archived first," which tells the agent when this tool will fail and routes it to archive_info first. It stops short of naming archive_info or unarchive_info as alternatives by name, so it is clear context rather than a full when/when-not map.

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 the safety profile is covered structurally. The description adds real value beyond them by disclosing that the revision history is deleted along with the document and that only archived items are eligible — a cascading/permanent effect the annotations alone do not convey.

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

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

Two tight sentences, zero filler, with the destructive nature and the precondition front-loaded in that order. Every clause 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 one-parameter destructive tool with no output schema and annotations covering safety, the description supplies everything an agent needs: what is destroyed, the cascading effect, and the required prior state. Nothing material 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?

Single 'id' parameter with 100% schema description coverage, so the schema carries the semantics and baseline 3 applies. The description adds nothing about the id format or how to obtain it beyond what the schema states.

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 ('Permanently delete') and resource ('an archived instruction document'), and scopes it to the archived state so an agent can distinguish it from archive_instruction/unarchive_instruction and from non-destructive delete siblings. No ambiguity about what the tool acts on.

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 an explicit precondition: 'Active instructions must be archived first,' which effectively routes the agent to the archive step before deletion. It stops short of naming the sibling tool or stating post-deletion state, but the when/when-not 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 declare destructiveHint=true and idempotentHint=false, but the description adds substantive context beyond them: the full cascade of destroyed dependent entities (Ideas, Batches, Works, Deliveries, Workflows, etc.), the permanence, and the confirmName equality requirement. That is exactly the extra behavioral detail a destructive tool benefits from.

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 highest-consequence fact (permanent delete), then cascading scope, then the confirmation guard, then the alternative. The long entity list is justified by the destructive nature and 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?

No output schema exists, and the annotations cover the safety profile; the description fills the remaining gaps (what is destroyed, the confirmation guard, the archive alternative) fully for a two-parameter destructive call.

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

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

Schema coverage is 100% and both parameters are already documented ('Id of the Project', 'exact name, to confirm deletion'). The description's restatement of the confirmName constraint is redundant with the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a project') with an explicit enumeration of the scope of destruction. It distinguishes itself from the 'archive' sibling rather than from the delete_* family, which are all child-resource deletions.

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?

Names the alternative ('archive with kind project hides a project and keeps its records') and the condition that selects it, so the agent can route between permanently deleting vs. hiding. It stops short of a fully directive 'use X when...' phrasing, but the contrast is clear and actionable.

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 covered. The word 'Permanently' adds real value by signaling a hard delete as opposed to the archive_* soft-delete pattern in this server, but nothing is said about effects on rules referenced by rulebooks or reversibility.

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

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

A single front-loaded sentence with no filler or redundancy. It is arguably under-specified rather than verbose, which is a completeness issue, not a conciseness one.

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

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

For a one-parameter delete tool whose annotations already carry the destructive/read-only profile and whose schema fully documents the id, the description is nearly sufficient. The main gap is the absence of any note about consequences for rule references elsewhere.

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% for the single 'id' parameter, so the schema already documents it fully. The description adds no syntax, format, or constraint information beyond what the schema provides, making the baseline 3 correct.

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 (delete) and resource (rule) with a clear scope ('one rule'), which is enough to separate it from update_rule and create_rule. It does not, however, differentiate itself from the parallel archive_* / delete_* family beyond the name.

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

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

There is no guidance on when to delete a rule versus archiving or updating it, no prerequisites, and no mention of alternatives such as update_rule or delete_rulebook. The agent must infer usage entirely from the name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real blast-radius context the annotations do not carry: rules are deleted with the ruleset and workflow connections are detached. It stops short of stating what happens on a repeat call or whether any rollback exists.

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

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

A single sentence that front-loads the destructive nature and packs the cascade scope in without a wasted word.

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, the description plus annotations cover the essentials: what it destroys and what it detaches. Missing only edge-case behavior, such as deleting a ruleset still referenced by active workflows or an already-deleted id.

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?

Only one parameter, and the schema already documents it at 100% coverage ('Id of the Ruleset.'). The description adds no format or sourcing detail for the id, so the baseline 3 for high-coverage schemas 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 ('Permanently delete a ruleset') and adds scope detail: it also removes the ruleset's rules and detaches it from every workflow connection. That cascade scope distinguishes it from delete_rule and update_ruleset, though it never names a sibling explicitly.

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

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

There is no when-to-use guidance, no mention of the reversible 'archive' sibling as an alternative, and no prerequisites. The word 'Permanently' implies irreversibility in contrast to archive, but the agent must infer that routing on its own.

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 structurally. The description adds nothing beyond that — no statement of irreversibility, no note on whether dependent records (workflow steps, reports) are removed, and no permission requirements.

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

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

One short, front-loaded sentence with zero filler, which is appropriately sized for a one-parameter tool. However, brevity here is achieved through under-specification rather than economy, so it earns only a minimal-viable score.

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 operation with no output schema, the description omits any warning about permanence, recovery options (no restore tool exists for work, unlike restore_idea/unarchive_*), or side effects. An agent cannot tell what deleting a work item actually entails.

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

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

The single `id` parameter is fully documented in the schema (100% coverage) as 'Id of the Work.', so no description compensation is required. Baseline 3 applies since the description adds no 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 'Delete a work item' is essentially a restatement of the tool name and title, adding no specificity about scope, cascade behaviour, or how it differs from delete_project, delete_idea, delete_info and the other delete_* siblings. Only the resource is identifiable, and that comes from the name itself.

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

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

There is no guidance on when to use this tool versus alternatives such as archive_* (reversible hiding) or the other delete_* tools. No prerequisites or exclusions are given; the agent must infer everything from the name.

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

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

Goes well beyond the destructiveHint annotation by enumerating exactly what is destroyed (runs, step reports, revisions) and, crucially, what survives (Batches, Deliveries, tool calls). It also discloses the confirmName safety guard, which is precisely the kind of consequence detail annotations cannot express.

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

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

Four tight sentences, front-loaded with the destructive action and scope, then retention, then the safety requirement, then the alternative. No filler; every clause carries actionable 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 fully carries the needed context: cascade effects, retained entities, the confirmation requirement, and the archiving alternative. Nothing an agent needs to invoke this destructively and 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 the baseline is 3, but the description adds real semantics: confirmName must equal the workflow's exact name, clarifying the confirmation guard beyond the schema's terse 'to confirm deletion'. projectId/workflowId semantics are left to the schema, which is acceptable given full 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?

States a specific verb and resource ('Permanently delete a workflow') and immediately scopes the cascade ('together with all of its runs, step reports, and revisions'). It also names the contrasting sibling behavior ('archive with kind workflow hides a workflow and keeps its history'), so an agent can distinguish destructive from non-destructive removal without opening schemas.

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

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

Explicitly names the alternative path (archive with kind workflow) and its key property (keeps history), giving a clear steer between permanent deletion and archiving. It stops short of an explicit 'use this when… / don't use this when…' framing, so the selection condition is strong but slightly 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 declare destructiveHint=true, and the description explains exactly what the destruction does ('Replaces the Work description with the factual implementedSummary'). It also discloses non-obvious behaviors: batch closing in the same call, the response asking only for the missing summary, re-invocation semantics, and finishing planned/in-progress works — all far 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?

Five sentences, purpose front-loaded first. Each sentence carries distinct behavioral content (replacement, batch closing, response contract, re-invocation, scope). Slightly dense, but little waste.

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

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

For a 4-param mutation tool with no output schema and complex Work/Batch lifecycle semantics, the description covers the tricky cases (conditional batch closing, re-invocation to close an open Batch, finishing planned/in-progress works). It lacks any note on auth/permissions or error conditions, but is otherwise sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds conditional meaning the schema only implies: batchSummary is required specifically when this closes the Batch, and implementedSummary replaces the existing description. This raises it above the schema-only 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?

States a specific verb and resource ('Record completed repository implementation') and immediately distinguishes the operation from siblings by naming the boundary behavior it performs (replaces description, marks done). An agent can differentiate it from update_work, delete_work, and begin_work from the text alone.

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

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

Explicitly says when to use it ('Use it once implementation is complete') and describes the conditional batch-closing invocation. It doesn't name the obvious alternatives (e.g. update_work, begin_work) or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds behavioral nuance beyond that: delivery_presentation returns 'null when it has none', and instruction returns 'the text that run uses' during an open workflow run — useful state-dependent context.

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 verb/resource before the per-kind bullets, so the essential intent is immediate. The list is long but each bullet justifies itself by documenting a distinct return shape; the project bullet is dense with routing links and markdown resource syntax, which slightly hurts scannability.

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-value burden and does so for every kind, including the null case and the run-dependent instruction text. Combined with sibling routing, an agent has everything needed to call it correctly and interpret the result.

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% and the enum's own description is one line ('Kind of record to read.'), so the description meaningfully extends it by explaining what each of the ten kind values retrieves. It also clarifies the id semantics for delivery_presentation, adding value over the bare 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 ('Get one record by kind and id') and then enumerates every accepted `kind` with the fields each returns. It also names siblings (get_project_state, list_batches, search_works, list_ideas, list_deliveries) so an agent can distinguish this point-lookup from list/search tools.

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

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

Gives clear routing for follow-up actions ('For next steps call get_project_state; for records use list_batches, search_works...'), which tells the agent when to leave this tool. It does not explicitly state the precondition of already holding an id, but the 'by kind and id' framing and sibling routing make the use context 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the returned node shape (id, name, description, children), the handsOff flag and its inheritance to descendants, and the constraint that hands-off features cannot be changed.

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?

Roughly four sentences, front-loaded with purpose before return shape and parameters. Every sentence carries information, though the featureId sentence partially duplicates the schema and the revision note is slightly detached from the listed return fields.

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

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

With no output schema, the description correctly takes on the burden of describing the returned tree, including the root and the handsOff inheritance rule. It also notes the cross-tool revision dependency. Minor gap: it never states where 'revision' lives in the response, given the field list omitted it.

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

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

Schema description coverage is 100%, so both parameters are already documented, including featureId's 'read only this feature and the features under it'. The description restates that scoping behavior almost verbatim and adds no format, id-source, or default guidance, so baseline 3 is correct.

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 ('Get a project's features') and immediately narrows the shape with 'as a compact tree', plus names the sibling that consumes the result (update_features). An agent can distinguish this from get_project or list_projects 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 clear context: use the default call for the whole project tree, or 'Pass featureId to read just that feature and the features under it.' It also flags the downstream dependency ('update_features needs the returned revision'), which tells the agent when this call is a prerequisite. No explicit when-not-to-use exclusion, 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes beyond them by disclosing the nextAction contract, the developing.finishWorkId field, and an explicit scope exclusion ('reports only Pizza Developer records, never repository, runtime, Git, deployment, or agent presence state'). It does not describe pagination, size limits, or error behavior, but with annotations covering safety this is strong.

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 the nextAction routing rule are front-loaded, and the scope disclaimer closes it out. The middle enumeration of possible nextAction values is a long run-on sentence, but each branch carries actionable information 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?

Despite having no output schema, the description conveys the return contract in usable detail: nextAction, listed workflows with their open runs, batchSummary, and finishWorkId. For a read-only state tool with a single required parameter, an agent has everything needed to call it and interpret the result.

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% for the single projectId parameter, so the schema already carries the semantics. The description only implies 'one project' and adds no format or sourcing detail beyond it; 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?

States a specific verb and resource ('Get the planning state needed to resume work on one project') and immediately distinguishes itself from get_project by scoping to resumable planning state rather than project metadata. An agent can tell what it returns 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?

Explicitly routes the agent: nextAction is start_workflow when workflows exist, resume_workflow to continue an open run that already covers the request, otherwise begin_work / finish_work / create_work / create_batch_plan / project_complete with the condition for each. This is a near-complete when-to-use-which-sibling map.

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/openWorldHint=false/destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context by noting output is 'bounded summaries' and listing exactly which fields come back, which the schema/annotations do not convey.

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

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

Three short sentences, front-loaded with the core action and return shape, followed by the alternative and a domain note. No filler.

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

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

With no output schema, the description usefully enumerates the returned fields and notes boundedness, plus numbering semantics, giving an agent everything needed to call and interpret the 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 limit/offset/projectId are already documented. The note that batches are 'numbered sequentially per project (1,2,3…)' gives domain meaning useful for interpreting results, but adds nothing about parameter syntax. 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 (List) and resource (a project's batches) and enumerates the returned summary fields (id, number, name, status, queue position). It clearly differentiates itself from get by framing output as 'bounded summaries'.

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 routes the agent to `get` with kind batch when rationale/summary detail is needed, which cleanly separates the list mode from the detail mode. It does not, however, state any exclusion (e.g., when NOT to list, or pagination advice).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond the schema: the ordering (newest shipped first), the bounded summary field set, and the active-vs-archived default. It stops short of describing pagination defaults for limit/offset.

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

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

Three tight sentences with zero filler, front-loaded with the core action and result shape before the archived behavior and the pointer to the alternative tool. Every sentence carries information.

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

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

With no output schema, the description usefully enumerates the returned fields and their ordering, and it covers scope (active vs archived) and where to go for richer detail. Nothing an agent needs in order to select and call this list tool 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 all four parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the archived semantics but adds no syntax or format detail 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?

States a specific verb and resource ('List a project's deliveries') and immediately characterizes the result shape ('newest shipped first, as bounded summaries: id, name, shipped date, batch and Work counts, and whether it has a presentation'). This clearly distinguishes it from list-type siblings like list_batches and from the detail-oriented get.

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 the default scope ('Lists active deliveries; pass archived=true for archived ones') and routes the agent to an alternative when more detail is needed ('Call get with kind delivery for rationale, summary, and assigned batches'). The when-to-use-this vs when-to-use-get boundary is spelled out rather than 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds non-annotation context: results are 'bounded summaries' containing only id/word/aliases (not full definitions) and are returned in the vibe coder's own order. It does not mention pagination defaults or total counts, which keeps it short of 5.

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

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

Three short sentences, zero filler, and the primary action plus scope is front-loaded before the archived flag and the alternative-tool pointer.

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

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

With no output schema, the description usefully specifies the returned fields (id, word, aliases) and ordering, and annotations cover safety. It omits any note on paging behavior or what the boundary values mean, which is a minor but real gap for a paginated list 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%, with limit, offset, archived, and projectId all documented in the schema, so the baseline is 3. The description's only parameter insight is the archived toggle, which the schema already states ('True to list archived records instead of active ones'); it adds no syntax or default-value meaning beyond that.

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

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

States a specific verb (List) and resource (a project's dictionary terms), and disambiguates scope by naming the active-vs-archived variants. It also names the exact return shape (id, word, aliases) and routes the agent to `get` with kind dictionary_term for definitions, so an agent can separate it from `get` and from the other list_* siblings.

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

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

Explicit routing: pass archived=true to read archived terms, and use `get` with kind dictionary_term for the approved definition. Both the alternative tool and the condition that selects it are named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: results are summaries rather than full content, and they follow the coder's own ordering with front-first priority. It does not mention pagination behavior, though limit/offset exist.

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

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

Front-loaded with the core action, and each subsequent sentence carries distinct information (state semantics, planning relevance, alternative tool). Slightly dense with several ideas packed in, but no filler sentences.

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 responsibly characterizes the return (bounded summaries, defined ordering) and covers the state parameter fully. Annotations handle safety, and all parameters are documented. Only pagination/limit semantics are left unexplained, 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 baseline is 3, but the description adds real meaning to the state enum by explaining what archived and declined actually represent (completed vs. decided against with a reason) — going beyond the schema's terse 'Which Ideas to list.' The other three parameters are left to the schema.

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

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

States a specific verb and resource (List ideas) scoped to 'a project's ideas in one state,' and clarifies the output shape as 'bounded summaries in the vibe coder's own order.' An agent can distinguish this from get, search_works, and list_projects 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?

Explains the state selector semantics (active is default, archived were completed, declined were decided against) and identifies which subset feeds planning. It also names the alternative explicitly: 'Call get with kind idea for full content,' giving a clear condition for switching 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context: the output shape (id, title, one-line summary), the ordering (vibe coder's own order), and default vs archived listing behavior. It doesn't mention pagination semantics despite limit/offset params, which 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?

Four tight sentences: purpose, domain definition, filtering behavior, and a routing pointer. Front-loaded with the output shape and scope, 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?

Complete for a read-only list tool: purpose, output fields, ordering, archived switch, and escalation path to get are all present. Only pagination behavior is left to the schema, which is acceptable given readOnly annotations and full schema coverage.

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

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

Schema coverage is 100%, so all four parameters including limit/offset are documented in the schema. The description reinforces the archived parameter but adds no syntax or format detail beyond the schema. Baseline 3 applies 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 (List) and resource (Info pages) and even defines what 'Info' contains, distinguishing it from rules/features. An agent can tell this apart from siblings like list_rulesets or get without opening schemas.

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

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

Explicitly covers the archived variant ('pass archived=true for archived ones') and routes to the alternative tool for page text ('Call get with kind info'). Both the state selector and the read-depth alternative are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful access-scope detail (owned or shared) but says nothing about result ordering, pagination, or default 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?

One sentence, front-loaded with the verb and resource, and no filler whatsoever.

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

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

A simple, non-destructive read tool with a fully documented two-parameter schema and safety annotations. The description is complete enough for correct invocation, with only ordering/default-limit details left unstated.

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% — limit and offset are fully documented in the schema. The description adds no parameter 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?

Specific verb (List) plus resource (projects) with a scope qualifier — owned or shared with the signed-in user. This clearly separates it from get_project, though it does not name any sibling explicitly.

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

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

The scope statement implies when to use it (browse all accessible projects rather than fetch one), but there is no explicit guidance on when-not to use it or on paginating through results. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the shape of the returned data (rules plus an attachedTo map of workflows and connections), which matters since there is no output 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?

The core purpose is front-loaded in the first sentence, but the remaining text drifts into domain exposition (must/should semantics, when rules execute) and references another tool's parameter. For a one-parameter list operation, some of this narrative is tangential rather than load-bearing.

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 responsibly describes what comes back (each ruleset's rules and its attachedTo workflows/connections), so an agent knows what to expect. For a simple single-param read tool this is close to complete, though pagination or ordering behavior is unaddressed.

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

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

The single projectId parameter has 100% schema description coverage ('Id of the Project'), so the schema does the heavy lifting and baseline 3 applies. The description adds no format or constraint detail for the parameter; its mention of rulesetIds refers to update_workflow, not this tool's input.

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 specific verb and resource ('List the project's rulesets') and immediately scopes the output ('with their rules and, in attachedTo, the workflows and connections'). This is clearly distinguishable from create_ruleset, update_ruleset, delete_ruleset, and create_rule 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?

The description explains the domain model (what a ruleset is, when rules run) but never says when to call this tool versus siblings like check_rules, get, or list_workflows, nor any exclusion or precondition. The only routing-like hint is that rules are checked inside workflow runs, which is context about rulesets generally, not guidance for invoking 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: archived workflows are omitted by default and only surfaced when includeArchived is true, and it lists the entry-point types. It stops short of mentioning pagination or result size, which would be the remaining gap.

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

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

Three short sentences, front-loaded with the action and result shape, then the scoping rule. The middle sentence about a project having several workflows is slightly filler but still earns its place by clarifying the plural result.

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 contents and does so by enumerating the per-workflow fields. Combined with the archived-filter rule, an agent has enough to call this correctly; only pagination/ordering details are absent.

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 schema already documents both projectId and includeArchived, setting the baseline at 3. The description restates includeArchived's effect but adds no format, default, or interaction detail 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?

The description opens with a specific verb+resource ('List the project's workflows') and scopes it to a project, which distinguishes it cleanly from the singular sibling get_workflow. It even enumerates the fields returned (name, description, entry points, runnability, graph), so an agent knows exactly what it gets.

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

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

Usage is only implied: the plural 'list' versus the sibling get_workflow's singular fetch is left for the agent to infer. The one explicit routing rule is the includeArchived behavior, which is useful but narrow; there is no stated when-to-use/when-not guidance relative to list_projects or get_workflow.

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=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real substance on top: the subset-versus-complete-set rule per kind implicitly warns that unlisted records can be displaced, and it states hard preconditions (parentId 'must not be ready' for work; instructions accepted only in the self-improvement stage). It does not describe failure modes or whether reordering is reversible.

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 a single-sentence statement of the operation, then a bulleted list where each bullet carries distinct kind-specific semantics rather than filler. It is long, but the length is dictated by nine enum variants that each behave differently. Minor repetition of the 'parentId is the project' pattern across bullets is the only slack.

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 nine-variant mutation tool with no output schema, the description covers what an agent needs to construct a valid call: the orderedIds contract, per-kind parentId, completeness expectations, and the workflow-stage restriction. Return values are not needed since the agent only needs to know the resulting order, which is implied.

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 genuinely adds meaning beyond it. The schema for parentId explicitly defers to the description ('the tool description says what each kind takes'), and the description discharges that with a kind-by-kind mapping; it also clarifies orderedIds as a first-shown-first sequence with subset semantics.

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

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

Opens with a specific verb and resource plus the ordering semantics: 'Set the manual order of one kind of record, first shown first.' No sibling tool does ordering, so the agent can immediately distinguish it from the update_*/delete_* family. The 'one kind of record' framing scopes it precisely to the enum in 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?

The per-kind bullets give strong conditional guidance: which kinds need a parentId, which must be an exhaustive set ('every active Idea', 'every planned Batch') versus which tolerate a subset ('a subset keeps every other project in place'), and the stage constraint on 'instruction' during a workflow run. It never names an alternative tool or states when not to reorder, 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.

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

Adds traits the annotations do not convey: 'A report cannot be read back, edited, or withdrawn once sent' discloses irreversibility, and 'on behalf of the signed-in vibe coder' discloses the auth/identity context. The mandatory human-confirmation gate is behavioral context well beyond readOnlyHint=false and idempotentHint=false.

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

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

Front-loaded with scope and the negative constraint, then the confirmation protocol, then path/message guidance, then docs. Every sentence earns its place; slightly long, but no filler or repetition of the schema.

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

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

For a write tool with no output schema and three fully documented parameters, the description covers everything an agent needs: scope, consent protocol, irreversibility, path semantics, message expectations, and a docs link. Nothing required to call 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%, so the baseline is 3. The description still adds meaning over the schema: when to supply path ('when it is about a particular page (/projects/{id})') and how to phrase message ('say plainly what went wrong and what was expected'), plus the sequencing rule that userConfirmed must reflect approval of that exact report.

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 ('Report a problem with Pizza Developer itself') and immediately carves out the boundary that distinguishes it: the app, not a project tracked inside it. An agent can tell this apart from report_workflow_step and the project-scoped tools 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?

Explicit when/when-not: 'Never send one on your own initiative', requires showing the vibe coder the exact message and path first, and gating the call on explicit confirmation via userConfirmed: true. It also names the condition for using path (a particular page like /projects/{id}), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false with destructiveHint=false, so mutation-but-safe is known. The description adds real behavioral context beyond that: 'failed' blocks the step for another attempt, a completed self-improvement report closes the step, research content is never stored, and the response mechanism (instructions carried when one route follows, resume_workflow when several). It stops short of mentioning auth or error behavior, so not a 5.

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

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

Front-loaded with purpose, and every clause carries information, but the body is a dense run-on of semicolon-joined conditionals that is hard to parse on first read. Information density is high but structure is weak; a short bulleted when/when-not split would have served better.

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

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

No output schema exists, and the description compensates by explaining what the response carries (the next step's instructions, or instructions arriving after resume_workflow). Combined with the lifecycle/failure semantics, an agent has enough to call this correctly, though error and idempotency behavior is unaddressed.

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

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

Schema coverage is 100%, which sets a baseline of 3. The description earns above that by explaining the semantic weight of the fields beyond their schema text: 'failed blocks a step for another attempt' and the reason field 'describes what changed and why, or why nothing did,' which is richer than the schema's 'What happened and why.'

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 — reporting a workflow step's outcome and optional costs — and immediately scopes it against the lifecycle tools that would otherwise complete a step. An agent can tell it apart from resume_workflow or the lifecycle tools without opening the schema.

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

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

Explicit when-to-use cases are enumerated (no expected lifecycle tool, failure, self-improvement step, client score) and a when-not case is stated (a step with an expected lifecycle tool needs no report). The alternative for routing, resume_workflow, is named with its triggering condition.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, so safety is covered. The description adds real behavioral context beyond them: the restored idea lands at the BACK of the active planning order, which an agent cannot infer from the schema or annotations. It stops short of describing permissions or a response.

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 with no filler; the core action is front-loaded and the disambiguation note follows immediately. Every clause 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 single-parameter tool with no output schema and annotations covering the safety profile, the description supplies the key missing context (where the idea returns to, and the unarchive alternative). A brief note on the source state (declined) or permissions would make it fully 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?

Only one parameter (id), and schema coverage is 100% with its own description, so the schema does the work. The description adds no syntax, format, or validation detail beyond that, making the baseline 3 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?

States a specific verb (restore) and resource (declined idea) and adds the placement outcome (back of the active planning order). It also names the sibling that handles a different case (unarchive for archived ideas), letting an agent distinguish the two without opening schemas.

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

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

The second sentence gives a clear routing rule: archived ideas are restored with 'unarchive', implying this tool is for declined ideas. That is a genuine when/when-not signal, though it doesn't mention the counterpart action (decline_idea) that puts an idea into this state or any prerequisites.

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

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description carries real behavioral weight: at most one open run per workflow, re-delivery semantics when no edgeId is supplied, and that later calls return only instruction titles after first delivery. These stateful/side-effect traits are not derivable from 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?

Three sentences, front-loaded with the core action before the disambiguation and branch/delivery caveats. Dense and slightly clause-heavy, but no sentence is filler.

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

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

No output schema exists, and the description partly covers return shape — full step re-send versus instruction titles only. For a 4-param stateful tool with annotations only covering safety, this is largely sufficient, though auth/permission prerequisites go unstated.

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 genuine meaning: edgeId selects a configured branch (including one that names bypassed optional stages), and runId/workflowId are framed as alternative disambiguators for open runs.

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 gives a specific verb pair and resource: 'Reconcile and read an open workflow run, then deliver its current step.' That is enough to separate it from get_workflow (pure read) and start_workflow (new run), though it never names those siblings directly.

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 concrete selection rules — 'name it with runId or workflowId when several are open' and 'Pass an available edgeId before reporting to choose a configured branch' — plus the no-edgeId fallback. It stops short of naming an alternative tool for when resume is the wrong choice.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is known; the description adds the non-obvious constraint that only one step is undone and that revertibility depends on the state of contained work. It does not say what happens when the precondition fails (error vs. silent no-op), which is the remaining behavioral 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?

One sentence, front-loaded with the action and its direction, followed by the precondition and the exclusion clause. Every clause carries distinct information; nothing is padding.

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

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

For a single-parameter mutation with annotations covering safety and no output schema, the description supplies the state machine and preconditions an agent needs. It is slightly short of complete because failure behavior and idempotency are unspecified.

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% for the single 'id' parameter, so the schema already documents it fully. The description only implies that the id refers to a batch and adds no format or lookup guidance beyond that, which is the baseline for full 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?

'Move a batch one step back as an undo: developing → planned' states a specific verb, resource, and the exact state transition, which distinguishes it from update_batch and delete_batch without opening any schema. An agent immediately knows this is a reverse transition, not a generic edit.

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

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

It states an explicit precondition ('only while every work inside it is still planned') and an explicit exclusion ('Ready batches are frozen history and can't be reverted'). Both the when and the when-not are spelled out, so the agent can decide before calling.

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, destructiveHint=false and openWorldHint=false, so the description doesn't need to restate safety. It adds real behavioral context beyond that: default sort order, the trimmed-column return shape, and the batch-scoped meaning of `reference` (`1-2` = work 2 of batch 1) — a non-obvious domain rule.

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?

Roughly four sentences, front-loaded with purpose, ordering and return shape before the parameter guidance. Dense but every clause carries information; the parenthetical on `reference` could arguably be trimmed, but it clarifies a genuinely confusing identifier.

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 correctly carries the return contract by enumerating the trimmed fields and showing the escape hatch (`get` with kind work). Ordering, scoping, filtering, and the reference format are all covered — nothing an agent needs to call 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%, so baseline is 3, but the description adds interaction semantics the schema can't: `query` searches across every reachable project unless `projectId` is supplied, in which case it searches inside that project. It also elaborates `status` and `reference` beyond the enum values.

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

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

States a specific verb (list/find) and resource (Works), specifies the default ordering (newest-updated first) and the exact return projection (id, reference, title, size, status, batchId, projectId). It also distinguishes itself from the sibling `get` by pointing there for full detail, so an agent can route without opening either 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?

Explains the two usage modes clearly: pass projectId to scope to one project, and query searches titles/descriptions either globally or within that project. It names the alternative (`get` with kind work) for full detail. No explicit when-not-to-use case, which keeps it from a 5.

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

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

Annotations only declare it is not read-only and not destructive; the description adds the real behavioral payload: the run is pinned to the workflow's current revision, it returns its current step, a batch start skips the review step, edgeId can name the Batch stage route, retries against an open run return the same run, and a Batch run governs that Batch's Work queue. It even discloses the document dedup rule (re-sent documents return as uri 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?

The purpose and main input branches are front-loaded, and nearly every sentence carries distinct edge-case information. The single dense paragraph packs a lot of conditional clauses together, which slightly hurts scannability but wastes little.

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, nested objects, and no output schema, the description carries the return-value burden and does state what comes back (the current step) along with side effects on the Work queue and revision pinning. Error conditions and the precise shape of the returned step are not covered, which is the main residual 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 description coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: it explains how the batch object is used (planned and run started in one call, review step skipped) and what edgeId means (the Batch stage route). It does not explain the batch name pattern constraint, leaving that to the referenced create_batch_plan.

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 (start a run of one workflow) and enumerates the three valid starting points: an Idea, a planned existing Batch whose Work has not begun, or a new batch plan. It also names the contrast case (a workflow that starts at Delivery takes none of them) and the sibling tools that complete that path, so an agent can pick it apart from create_batch_plan and create_delivery.

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 clear selection logic across the mutually exclusive inputs and points to create_delivery/update_delivery for the Delivery-start variant, plus a retry-idempotency note. It stops short of explicitly contrasting with resume_workflow, cancel_workflow, or begin_work, so the when-not-to-use side is left to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so safety is covered. The description adds substantive state-change semantics the annotations cannot express: where each kind reappears (default dashboard, back of active planning order, Deliveries page plus public surfaces) and the workflow-run restriction.

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 action is front-loaded in the first line and the bullets are one line each, matching the seven-value enum without filler. No sentence is redundant with the schema or annotations.

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 outcome disclosure and does so per kind. Minor gaps remain around failure cases (record not archived, unknown id) and permission requirements, but an agent can invoke it correctly as written.

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% and the enum is documented generically in the schema, but the description goes further by mapping each of the seven enum values to its distinct post-unarchive behavior, which is exactly the information needed to choose the right kind. The only untouched parameter, id, is self-explanatory.

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 opening sentence names a specific verb and resource ('Unarchive one record by kind and id') and the per-kind bullets make the scope concrete. It also explicitly distinguishes itself from the sibling restore_idea, which handles declined ideas rather than archived ones.

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 bullets give the condition under which each kind applies and route the declined-idea case to restore_idea, plus a real usage constraint ('During an active workflow run, accepted only in its self-improvement stage'). It stops short of stating general when-not-to-use cases (e.g. record not currently archived) or error behavior.

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 flag destructiveHint=true; the description adds the far more useful behavioral facts: partial-update semantics, empty-string-clears behavior, the ready-state rejection rule, and the immutability of batch numbers. These are exactly the mutation behaviors an agent needs and none are derivable from annotations.

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

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

Front-loaded with the core mutation contract, which is good, but the tail drifts into tangential material (status flow via other tools, immutable batch numbers) that dilutes the edit-focused message. The prose is dense but several clauses don't serve this tool's 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 4-param mutation tool with no output schema, the description covers the destructive/partial-update profile, per-field rules, and the key state precondition. It doesn't state the return value, but without an output schema the caller may want to know what a successful update yields; that is the only notable 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 description coverage is 100%, so the baseline is 3, but the description adds real semantic constraints: the exact name grammar (1-3 lowercase hyphen-joined words with an example), the content rules for rationale and summary, and the empty-string-clears contract. This meaningfully exceeds what the schema's one-line descriptions convey.

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

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

The description opens with a specific verb (Edit) and enumerates the exact mutable fields (name, rationale, change summary), which immediately distinguishes it from siblings like update_work or update_delivery. The agent knows exactly what this tool mutates without opening the schema.

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

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

It gives explicit when-to-use signal (only supplied fields change) plus a critical exclusion: a ready batch refuses rationale and summary edits. It also points the agent toward begin_work, finish_work, and revert_batch for status changes, routing correctly away from 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 flag destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: partial-update semantics ('Only supplied fields change; pass an empty string to clear a text field'), the invariant that other batches stay put, the uniqueness/non-empty constraint on name, the no-future-date rule for shippedAt, and the return value ('Returns the delivery's resulting batches'). This is rich behavioral disclosure that the annotations alone do not convey.

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

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

The purpose and update semantics are front-loaded, and the later sentences about workflow-stage behavior earn their place by disambiguating a non-obvious side effect. It is dense but each sentence carries distinct information; only the workflow-stage sentences feel slightly long-winded.

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 mutation tool with nested objects and no output schema, the description covers mutation semantics, constraints, batch-movement rules, and the return value, which is a lot. The only shortfall is the unmentioned metrics parameter, whose behavior (stored on the workflow step) is left entirely to the 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: empty-string-clears semantics for text fields, name uniqueness within a project, ISO format and not-in-the-future constraint for shippedAt, and that addBatchIds only accepts ready batches no other delivery carries. The one gap is that the metrics object is never mentioned in the description, though the schema documents it.

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

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

The description opens with a specific verb and resource ('Edit a delivery's own record (name, rationale, summary, ship date) and add or remove its batches'), which immediately distinguishes it from the sibling create_delivery, delete_delivery, and list_deliveries tools. An agent can tell exactly what record is touched and what sub-operations are included.

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

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

It gives explicit preconditions and alternatives: 'Take a batch out of its current delivery before adding it to another', and it names create_delivery as the alternative along with the exact condition that selects update_delivery instead ('adding every ready Batch of the run to one existing Delivery completes the stage instead of create_delivery'). This is more than implied usage — it routes the agent between sibling 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 already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is known. The description adds valuable behavioral context: it replaces the current presentation while earlier versions remain restorable, invalid presentations return field-level errors, and it explains brand sourcing rules and that no source code is included.

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 long but front-loaded with the core purpose and each sentence adds relevant information about content sourcing, timing, replacement, and validation. It could be more scannable with structure, but given the schema's complexity the length is largely justified and there is little waste.

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

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

Given the complex nested schema and the absence of an output schema, the description covers the key behaviors an agent needs: destructive replacement with restorable history, brand derivation, scene timing constraints, and validation errors. It does not discuss permissions or id requirements, but those are minor omissions for 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?

Schema coverage is 100%, so the schema documents all field structures. The description nonetheless adds semantic meaning beyond the schema: it defines the timing rule for 'seconds' (at least reading time, about 1.5 seconds plus one second per three words, minimum 3 seconds, whole seconds, 60-second total cap) and explains that brand colors, radius, and font come from the product's own logo and styles.

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 ('Save') and resource ('a delivery's release presentation'), then details the content and presentation rules. An agent can immediately tell this is the write tool for a delivery's presentation, distinct from get/delete siblings.

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

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

The description explains what the tool does and its constraints but never states when to use this tool versus alternatives such as update_delivery, get_delivery_presentation, or delete_delivery_presentation. No explicit when-to-use or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered. The description adds genuinely useful patch semantics ('only the fields you provide change'), which tells the agent that omitted fields are preserved. It does not explain what makes the operation destructive, whether clearing a field is possible, or any permission requirements.

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

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

Two short sentences with zero filler; the core action is front-loaded and the patch semantic follows immediately. Nothing could be removed without losing meaning.

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

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

For a four-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description is minimally adequate. It could do more for a destructiveHint=true update: explaining whether fields can be cleared, what happens to aliases when omitted, and how failures are surfaced. No output schema exists, so return values would be helpful context but are not required.

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 all four parameters (id, word, aliases, definition) are already documented in the schema, making 3 the baseline. The partial-update sentence mildly informs how optional parameters behave but adds no format or constraint detail 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 names a specific verb (Update) and resource (dictionary term), so an agent can distinguish it from create_dictionary_term, get_dictionary_term, and delete_dictionary_term. It does not, however, explicitly differentiate itself from archive/unarchive or state what updating accomplishes beyond the verb.

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

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

There is no statement of when to use this tool versus siblings like archive_dictionary_term, delete_dictionary_term, or create_dictionary_term. The only guidance offered is the partial-update clause, which is a behavioral detail rather than a usage condition.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses atomic in-order application, optimistic-concurrency refusal of stale writes, cascade deletion for remove, the hands-off protection rule (features and descendants), and the browser-editing lock. This is exactly the behavioral context a mutation tool needs.

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 operations and packs constraints into a dense paragraph with no filler. It is a single long run-on rather than clearly separated bullets, which slightly hurts scanability, but every clause carries required information.

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

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

For a complex no-output-schema mutation tool, the description covers atomicity, revision semantics (including the returned revision for chaining), protection rules, and concurrency refusals. Nothing an agent needs in order to call 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 the baseline is 3, but the description adds meaning the schema does not: parentId null means top level, remove deletes the entire subtree, update accepts name and/or description, and move takes an optional position. These are real semantics layered on the structured fields.

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

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

States a specific verb (Change) and resource (a project's features) and enumerates the four supported operations (add, update, move, remove) with their sub-semantics. An agent can immediately distinguish this from the read-side sibling get_features and from the update_* family for other resources.

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 how to use it contextually: changes must be based on baseRevision from get_features, and large restructures should be split into several calls each using the revision the previous one returned. It does not name a competing alternative tool, but no sibling offers feature editing, so the guidance is effectively complete for routing.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description confirms the destructive 'replace' semantics and explains that an empty note clears the handoff. It adds what the write representatives know: overwriting existing content and how to intentionally clear it. It doesn't mention permissions or failure behavior, but goes well beyond the annotations.

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

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

Two front-loaded sentences: the first defines the action and content, the second covers lifecycle relationships and the empty-note rule. Every clause 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 two-parameter write tool with destructive hint annotations and no output schema, the description covers action, content expectations, lifecycle interaction, and the clearing behavior. It omits any note about return value or confirmation, but annotations and schema cover the remaining structured detail adequately.

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 goes further by defining what the 'note' parameter should contain and that an empty string is a valid way to clear the note, adding real meaning beyond the schema's maxLength limit. It does not expand on workId, which the schema already documents.

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 ('Replace the handoff note on the Work') plus scope ('so another session can continue it'). It clearly distinguishes itself from sibling tools begin_work and finish_work by describing their differing roles, so an agent can recognize what it 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?

Explains the note's intended content (done, remains, files touched, uncommitted changes) and names the related lifecycle tools begin_work (returns it) and finish_work (clears it). It also gives an operational rule: pass an empty note to clear it. There is no explicit 'use this when...' trigger, 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?

With readOnlyHint=false and destructiveHint=true already declared, the description usefully adds partial-update semantics ('Only supplied fields change') and clarifies that nothing downstream is generated. However, it never states reversibility or whether an update triggers rules, and the trailing sentence about archiving/declining/restoring not running rules creates ambiguity about the update path itself.

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 scope and mutation semantics in short, terse sentences with no filler. The final sentence about archiving/declining/restoring not running rules is tangential to this tool's purpose and slightly muddies an otherwise tight block.

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 partial-update mutation tool with no output schema and full schema documentation, the description covers the essentials: which fields change, that unspecified fields are untouched, and where ordering belongs. Nothing critical 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 the schema already documents id, title (<=20 chars), impact enum, content, and summary. The description repeats the 20-character title constraint but omits the 'summary' parameter entirely, adding little beyond the structured fields. 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 concrete verb+resource (update an idea) and enumerates the mutable fields (short name <=20 chars, detail, impact). It also actively distinguishes itself from the sibling 'reorder' for ordering and from the archive/decline/restore family, so an agent can route without opening other 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?

Gives explicit routing for one alternative: 'Order is separate: move an idea with reorder,' which is exactly the kind of disambiguation an agent needs. It does not cover other nearby choices (delete_idea, archive_idea, restore_idea as the actual update targets), so it stops short of full when/when-not guidance.

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

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

Annotations flag destructiveHint=true, but the description goes further and explains the actual destruction semantics: only supplied fields change, content replaces the entire text rather than appending, and an empty string clears content or summary. It also discloses that prior text survives in revision history, giving the agent a recoverability signal the annotations do not carry.

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

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

Four short sentences, each carrying distinct information: what can be changed, how partial updates behave, what clearing does, and what the read-first prerequisite is. The scope statement is front-loaded 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?

For a mutation tool with no output schema, the description covers the important gaps: mutation scope, replacement vs. merge behavior, clearing semantics, and recoverability via revision history. It is slightly thin on what the call returns or whether the updated page is echoed back, but that is a minor omission given the schema documents all four inputs.

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, and the description adds genuine meaning on top: the partial-update rule ('Only supplied fields change'), full-replacement semantics for content, and the empty-string clearing convention for both content and summary. It does not, however, restate the id parameter's role or the 200-char summary cap.

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 ('Rename an Info page, change its summary, or rewrite its text whole') and enumerates exactly which fields are editable, which distinguishes it from create_info/delete_info and from the update_* siblings for other resource types.

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 a prerequisite workflow: 'Read the current text with get, kind info, first,' naming a concrete sibling and parameter. It gives clear when-to-use context but offers no when-not guidance (e.g., use create_info if no page exists yet, or update_* for other resource kinds).

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 past the annotations by disclosing that only supplied fields change, that content wholesale replaces the text, that an empty string clears it, that prior text survives in revision history, and that workflow runs gate edits to a specific stage. This is exactly the destructive-mutation context an agent needs.

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

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

Four tight sentences, each carrying distinct information, with the rename/rewrite purpose front-loaded and 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-parameter mutation tool with no output schema, it covers purpose, mutation semantics, prerequisites, history behavior, and workflow-stage gating; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: the partial-update contract ('only supplied fields change') and the full-replacement/clear semantics of content are not spelled out in the schema.

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

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

States a precise verb+resource: 'Rename an instruction document or rewrite its text whole.' It is clearly distinct from update_rule/update_info/update_work by naming the resource, but it never explicitly contrasts itself with those siblings.

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

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

Gives a concrete prerequisite ('Read current text with get, kind instruction, first') and a conditional constraint ('instruction changes are accepted only in its self-improvement stage'). No explicit when-not or named alternative (e.g., delete_instruction), so it stops short of a 5.

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