Meta Council

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

Annotations only declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail beyond that: credentials are withheld (with specifics like password hashes, tokens), some tables are deliberately excluded (referenced to docs), and the export is bounded (per-model truncation with envelope completeness). It also clarifies it is not erasure or compliance, and states auth/scope requirements. No contradiction with annotations.

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

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

The description is long but each sentence adds value: purpose, exclusions, credential behavior, pagination tactic, clarification of non-compliance, and auth requirement. It's front-loaded with the core function and structured logically, though a bit dense. It earns its length for a complex tool.

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

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

For a tool with no output schema, the description covers all necessary aspects: behavior, exclusions, credentials, pagination, auth/scope, and points to docs for further details. An agent can correctly call it knowing what it does, how to page, and what to expect in the response envelope.

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?

Though schema coverage is 100%, the description enriches parameter meaning: it explains that 'models' is for narrowing to page truncated tables, and that 'rows_per_model' is a per-model ceiling with defaults and max. This goes beyond the schema's bare descriptions, helping an agent understand how to use them together for pagination.

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

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

Description uses a specific verb ('Export') and clearly defines the resource ('this account's own data across every table the account owns'). It also specifies the format ('same JSON envelope the REST route returns'). By emphasizing 'this account's own data', it distinguishes itself from potential siblings like audit_export, which might cover broader scopes.

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

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

Provides explicit context on when to use it: it's a data export, not an erasure request or compliance claim. It also explains pagination strategy (narrow to one model, raise rows_per_model) and points to documentation for exclusions. It doesn't name specific alternative tools, but the constraints and exclusions are clear enough for an agent to decide.

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

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

Beyond the annotations, the description reveals significant non-obvious behavior: the call is atomic, any invalid run rejects the entire operation, and the set remains unchanged on failure. It also states the required permission scope (comparisons:write), which the agent cannot infer from 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 description is two sentences with every clause contributing: operation, ownership/status precondition, atomicity, rollback guarantee, and permission. The primary action is front-loaded and the exception behavior follows compactly without 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 two-required-param mutation with no output schema, the description is complete: it covers the action, preconditions, failure semantics, rollback behavior, and authentication scope. There are no hidden edge cases that would prevent a correct invocation.

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

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

With 0% schema description coverage, the description must supply parameter meaning, and it does: session_ids are the runs to append, and set_id is the target set. It also attaches value constraints (finished, owned, not already a member) to those parameters. The only gap is that it never explicitly names set_id or session_ids.

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

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

The description uses a specific verb and resource: 'Append finished runs you own to a set.' It clearly differentiates this operation from set-creation and set-inspection sibling tools. The all-or-nothing detail reinforces that this is a mutation of an existing comparison set.

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

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

It clearly identifies the intended use case: adding already-finished, owned runs to a set, and lists the reasons a call would be refused. It does not explicitly name alternative tools such as create_comparison_set, but the context is unambiguous enough to route an agent correctly.

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

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

The description discloses that totals are recomputed automatically and that the operation is blocked on paid/void invoices. These are behavioral traits not covered by the annotations (which only indicate non-readonly, non-destructive, non-idempotent). No contradiction with annotations is present.

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

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

The description is two concise sentences with no redundancy. It front-loads the main purpose and then adds critical constraints and requirements. 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?

The description covers the essential usage context (when it works, automatic recalculation, blocking conditions) and notes invoice_id as required. However, it omits details about unit_price and description parameters, which are not explained in the schema either. Given the lack of an output schema, the description provides enough to understand the operation but leaves parameter semantics unclear for an agent.

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

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

Schema description coverage is only 25% (only quantity has a description). The description only mentions that invoice_id is required, which is already in the schema. It doesn't explain the meaning or expected format of unit_price or description, leaving the agent without additional semantic guidance for the core parameters. It fails to compensate for the low 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?

The description clearly states the action (add a billable line item), the target resource (invoice), and specific constraints (draft/sent, blocked on paid/void). It distinguishes itself from sibling tools like create_invoice or update_invoice by specifying exactly what it does and its scope.

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 indicates when to use it (adding a line item to a draft or sent invoice) and states a limitation (blocked once paid/void). It doesn't explicitly name alternatives or when-not-to-use scenarios, but the context and constraints make the intended usage clear enough.

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 (readOnly=false, destructive=false, openWorld=false), and the description adds real behavioral context beyond them: authentication is required, the tool stamps provenance source="agent" server-side, and it explicitly sends no email. It stops short of saying what happens on duplicate emails or with an empty payload, which matters given 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?

Four short sentences, front-loaded with the core action and return value, then side-effect boundaries. Nothing is wasted, though 'Requires authentication' is a fairly generic tail statement.

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 compensates by stating the return value (new lead id). For a mutation tool it covers auth, side effects, and provenance; the remaining gap is behavior on duplicates and on an all-optional empty payload.

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

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

Schema description coverage is 100%, so every one of the 7 optional fields is already documented in the schema (including that omitted email means held research). The description adds no per-parameter meaning of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a single lead to the authenticated user's outreach book') and scopes it to one lead, which implicitly separates it from bulk or search operations like search_outreach_leads. It never names a sibling explicitly, so the differentiation is inferential rather than stated.

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

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

Usage is only implied: an agent infers it should call this when it wants to create a lead. The clause 'Does not send any email' does helpfully signal this is not the outreach-sending path, but there is no explicit when-to-use vs. when-not guidance or pointer to update_outreach_lead_status / search_outreach_leads.

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 openWorldHint=true, so the safety profile is partly carried structurally. The description usefully adds that auth is required and that the call resumes a paused pipeline, but it never explains the destructive side (e.g. that 'reject' terminates/abandons the step or that the action is not repeatable) — the most important behavioral caveat for this tool.

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

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

Two tight sentences, zero filler, with the core action front-loaded before the session-id sourcing and auth note.

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 non-idempotent, destructive, authenticated mutation with no output schema, the description covers purpose, checkpoint precondition, parameter provenance, and auth. The one gap is the consequence of a reject decision and any irreversibility, which an agent deciding between approve/reject would benefit from.

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 would be 3. The description goes beyond the schema by stating where session_id comes from (run_workflow / get_workflow_session) and that the session must be checkpoint-paused, which is real operational meaning the schema does not supply.

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 ('advance') plus resource ('workflow') plus the exact semantic moment ('past a human checkpoint — approve or reject the paused step'). Clearly distinguishable from run_workflow, retry_workflow, and get_workflow_session in the sibling list.

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

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

Tells the agent to use the session id from run_workflow / get_workflow_session and that the session must be paused at a checkpoint, which is clear situational guidance. It stops short of explicitly contrasting with retry_workflow or decide_approval, so no 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 already disclose the mutation/idempotency profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the description's job is to add context. It does: the required scope 'consulting:approve' and the boundary that approval does not publish or send. It does not describe error behavior when the version or hash mismatches, which is a meaningful gap for a guarded mutation.

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

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

Two sentences, no filler; the core action is front-loaded and the constraint clauses follow. Every clause carries unique 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 3-required-parameter guarded mutation with no output schema and no schema descriptions, the description covers permissions and scope but leaves the concurrency contract and failure modes unexplained. Adequate as a minimum, but an agent still cannot tell how to satisfy expected_version/expected_content_hash correctly.

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

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

The description says nothing about deliverable_id, expected_version, or expected_content_hash, and schema description coverage is 0%. Those three required parameters encode optimistic-concurrency semantics (version plus content hash guard) that the agent cannot infer, and the description does not compensate.

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 (approve), a specific resource (one submitted internal deliverable), and an added effect (record approver evidence). The word 'submitted' scopes it against create_consulting_deliverable/update_consulting_deliverable, and the singular 'one' separates it from batch operations.

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 clear precondition ('Requires consulting:approve') and an explicit exclusion ('never publishes or sends it'), which tells the agent this is an internal-only approval. It stops short of naming when to prefer this over siblings like approve_consulting_document_revision, so it is not a full when/when-not routing statement.

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 idempotentHint=true, so the mutation profile is partly covered. The description adds real value beyond that: the lock semantics, the distinct OAuth scope requirement, and the explicit statement that approval does not publish or share the revision.

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, front-loaded with the action and followed by the distinguishing constraints. Nothing is redundant or padded.

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, idempotent approval with no output schema, the description covers the essential unknowns: scope requirement and non-publishing behavior. The remaining gap is failure behavior on version/hash mismatch, which is minor for an agent deciding whether and how to call 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 0% for 3 parameters, so the description carries the burden. The phrase 'one exact proposal/SOW revision' hints that document_id, expected_version, and expected_content_hash must match a specific revision, but it never explains the concurrency/version-check semantics or what a mismatch does, leaving the parameters largely unexplained.

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 (approve and lock) and a precise resource (one exact proposal/SOW revision), which distinguishes it from sibling approve_consulting_deliverable and submit_consulting_deliverable. It stops short of naming those siblings, but the resource scoping is clear enough for an agent to route correctly.

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

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

The description gives the precondition (requires the separate consulting:approve scope) and a boundary (never publishes or shares), which implies when this tool is appropriate. It does not say when to use it instead of update_consulting_document_revision or approve_consulting_deliverable, so the when-not guidance 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 already declare non-readonly, destructive, non-idempotent behavior, so the bar is lower. The description still adds meaningful context: the required permission scope (marketing:approve, distinct from draft authority) and the hash-attestation semantic, which implies the approval binds to exact content. It does not explain the destructive consequence or reversibility, which keeps it from a 5.

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

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

Two short sentences with no waste; the core action is front-loaded and the prerequisite follows immediately. Every clause carries information the agent needs.

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

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

For a destructive, non-idempotent approval mutation with no output schema, the description covers the permission gate and the hash-attestation meaning, which is the minimum viable. It is silent on approval side effects, reversibility, and the purpose of the notes parameter, so an agent still lacks full context.

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 only 50%: asset_id is documented as 'Full UUID from the matching list tool', but notes has no description at all. The tool description never mentions the optional notes parameter, so it does not compensate for the coverage gap beyond loosely implying that asset_id identifies the revision.

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 ('Approve a submitted owned revision') and adds a distinctive semantic, attesting to the exact content hash. It implicitly differentiates itself from draft-approval authority in the sibling set, though it does not name a sibling 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?

The description gives a prerequisite ('Requires marketing:approve, separate from draft authority'), which is useful context for when this call will succeed. However, it never states when to choose this over reject_content_asset or the consulting approval siblings, nor what conditions must hold for a revision to be approvable.

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 beyond the annotations by disclosing conditional failure ("changed input refuses") — content-addressed concurrency protection — plus the required auth scope (outreach:write) and the fact that approval has no downstream side effects (no consent, enrollment, or send). Annotations only state readOnly=false and destructive=false; the description adds the refusal semantics and permission requirement.

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

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

Four short sentences, front-loaded with the action and its binding scope, then the hash contract, then exclusions, then the auth requirement. Every clause carries distinct information with no filler.

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

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

For a write tool with no output schema and only machine-generated annotations, the description supplies the mutation semantics, the idempotency/refusal behavior, the non-effects, and the permission scope. It is close to complete, missing mainly what a successful approval returns and the meaning of lead_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?

Schema description coverage is 0%, so the description carries the burden, and it does explain the critical expected_draft_sha256 contract against the reviewed draft and ties the optional fields (recipient, subject, body) to the approval binding. However, lead_id — a required parameter — is never explained, and the parameters are not enumerated individually, so the description only partially compensates for the coverage gap.

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

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

Specific verb+resource: "Record exact draft approval" with the binding scope (recipient, campaign, subject, body) spelled out, and it explicitly carves out what it is not ("does not create consent, enroll or send"). It differentiates against the send/enroll side of the outreach toolset, though it does not name the closest sibling writers (record_outreach_evidence, draft_outreach_email) that an agent might confuse it with.

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 clear operating condition and prerequisite: supply the reviewed draft_sha256 as expected_draft_sha256, requires outreach:write, and negative guidance that approving does not create consent or trigger enrollment/send. No explicit named alternative is offered, 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?

The description directly asserts 'Idempotent -- archiving twice keeps the original archive time', but the annotations declare idempotentHint=false. That is a contradiction of a structured behavioral hint, and per the rubric a contradicting description scores 1. The remaining disclosure (non-destructive, keeps definition, auth + tickets:write scope, does not hide from a shared team) is genuinely valuable, but the idempotency claim conflicts with the declared hint.

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 dense paragraph, front-loaded with the effect and reversibility, then the alternatives, then idempotency, then scope caveats and auth. Every clause carries information; 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?

Covers reversibility, sibling routing, shared-view scope, auth and required scope - complete enough for a mutation tool with no output schema. The one soft spot is that the idempotency statement is inconsistent with the declared hint, so the agent's picture of repeat-call behavior is not fully reliable.

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 view_id and expected_revision are already fully documented in the schema; baseline 3 applies. The description adds only the implicit ownership constraint ('YOUR OWN') and nothing about the optimistic-concurrency parameter, so it does not add 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?

States a precise verb+resource ('retire one of YOUR OWN saved views') and immediately distinguishes the operation from its siblings by naming delete_saved_view, restore_saved_view and execute_saved_view. An agent can tell exactly what this does and does not do without opening a schema.

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

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

Explicitly routes the agent: 'Prefer this over delete_saved_view', plus the consequences that make that choice concrete (drops out of default listing, execute_saved_view refuses it) and the restore path. It also sets the ownership boundary by stating this is the caller's own working 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 idempotentHint=true and destructiveHint=false, but the description adds real substance beyond them: the concrete idempotency mechanism ('exact request retries recover the original result'), the effect boundary (retains immutable captures and a revision tombstone, no provider call or remote unlink), and the required scope 'tickets:write'. That is the auth and side-effect context an agent needs before invoking a mutation.

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

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

Four tight sentences, front-loaded with purpose, then effects, retry semantics, and required scope. No filler and every clause carries an operational 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 mutation with no output schema, it covers effect scope, idempotency, and authorization. It stops short of stating what the caller gets back (e.g., a tombstone/revision reference) or what error occurs on a revision mismatch, which an agent handling conflicts would want.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it only partially does: 'exact revision' explains expected_revision as a concurrency token and 'exact request retries' implies request_id is an idempotency key, but ticket_id and the provider enum 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?

States a specific verb and resource ('Archive an owned provider field link'), and the qualifier 'using its exact revision' pins the exact operation. This is clearly separable from the many other archive siblings (ticket_archive, archive_saved_view, ticket_label_archive) because the resource is named precisely.

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

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

Usage is implied by the verb ('Archive'), and it clarifies scope with 'no provider call or remote unlink', but it never states when to choose this over link_ticket_provider_fields or the ticket-level archive tools, nor what prerequisites state the link must be in.

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

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

The description goes substantially beyond the annotations. It discloses the return type ('legal_evidence_graph/v1'), the requirement for authentication and specific schema version, the disabled generated mode, the withholding of verdict prose, and the 'fixed server text' rendering of provider assertions. It also notes the atomic spend reservation and operator gate. These are non-obvious behaviors that an agent needs to know, adding significant value over the readOnlyHint and idempotentHint annotations.

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

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

The description is a single dense paragraph with multiple clauses and technical jargon (e.g., 'THEMIS_NEUTRAL_SCHEMA_VERSION', 'atomic spend reservation', 'enum codes linked to evidence'). While informative, it lacks structure (no bullets or sections) and is not front-loaded for readability. It could be broken into shorter sentences or bullet points for easier parsing by an agent, making it less concise than optimal.

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

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

Given the tool's complexity (10 params, no output schema, nested objects, authentication needs), the description is remarkably complete. It covers the return type, the disabled mode, permission requirements, safety caveats, and provider fidelity limitations. An agent would have enough context to call the tool correctly and interpret results, even without an output schema. This is a comprehensive definition.

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

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

The input schema provides 100% coverage with detailed descriptions for each parameter (e.g., question max length, domains enum, quality default). The tool description does not repeat or add much parameter-specific meaning; it mainly describes overall behavior (e.g., request records, attach plan) rather than clarifying individual parameters. Baseline of 3 applies because schema already carries the descriptive load, and the description adds marginal value here.

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

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

The description clearly states the tool's function: requesting legacy Themis source/citation records and attaching a proposed research plan. It specifies the resource (Themis records) and the action (request and attach). It also mentions 'Check the law uses fixed legacy provider-record retrieval,' reinforcing the purpose. No sibling tool serves this legal-research function, so it stands apart distinctly.

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

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

The description provides context on when this tool is usable (requires 'legal:run' permission) and when it is not (generated mode disabled due to missing manifest verifier). It also clarifies limitations ('Automated research only, not legal advice'), which guides appropriate use. However, it does not explicitly mention alternative tools or exclusion criteria because no direct sibling exists; the guidance is indirect but sufficient.

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

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

The description claims 'Idempotent' while the annotation idempotentHint is false. This is a direct contradiction, which severely misleads an agent about the tool's behavior. Any other behavioral notes (returns count, requires auth) are overshadowed by this inconsistency.

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

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

The description is a single efficient sentence with all key facts front-loaded: action, ownership, return value, idempotency, and auth. No wasted words.

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

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

For a simple two-parameter tool, the description covers the essentials, but the contradiction on idempotency leaves the agent uncertain about retry behavior. This gap prevents full 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% with descriptions pointing to source tools for both parameters. The description adds the ownership constraint that applies to both parameters, but no further parameter-level detail. Baseline 3 is appropriate.

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

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

The description clearly states the action (assign), the resource (leads to campaign), and the ownership constraint. It distinguishes from sibling tools like search_outreach_leads or create_outreach_campaign by specifying 'existing leads' and 'existing campaigns' owned by the caller.

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

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

The description implies usage by indicating leads and campaigns must already exist and be owned by the caller, which is a prerequisite. It doesn't explicitly name alternatives, but the context is clear enough for an agent to know when to apply this tool versus others.

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 significant disclosure beyond the annotations: explicitly states that no prompt text, document content, tool arguments, or model output is ever returned; requires authentication and the audit:read scope; describes ordering (oldest first), pagination via cursor, and the coverage block on every response. Annotations already cover read-only, idempotent, and non-destructive hints, and the description complements these with concrete behavioral details.

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 dense but every sentence adds value: purpose, event contents, exclusions, filtering, pagination, coverage caveat, and authentication. It is well-structured with the core purpose front-loaded. It is a bit long but warranted given the tool's complexity.

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 tool with no output schema, the description is remarkably complete: it explains what each event carries, how to paginate, what is excluded, coverage limits, and authentication requirements. It even points to external docs for the full action list. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description reinforces the purpose of since/until/action and the after_id cursor, but does not add new semantics beyond what the schema already provides. The baseline of 3 applies because 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?

The description clearly states the verb (export) and resource (workspace's own agent-action audit trail), and specifies the use case (loading into a SIEM). It differentiates from the sibling account_export by scoping to workspace and explicitly stating what is excluded (metadata only, no prompt text, etc.).

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 clear context for when to use: for SIEM loading, with filtering by date and action, and pagination. It notes that it covers a documented subset of platform activity rather than every action, which guides usage away from full-coverage expectations. It points to docs/WORKSPACE_AUDIT_EXPORT.md for details. It does not explicitly name an alternative tool, but the subset caveat serves as an implicit exclusion.

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, openWorldHint=true and idempotentHint=true, and the description reinforces rather than contradicts them: it discloses the recipient-notification side effect (and cancellation risk) and explains the retry contract ('reuse the same preview, hash and confirmation reference after uncertainty'). It also details a recovery branch (missing custody permits allow receipt recovery but cannot authorize a new dispatch) that adds genuine behavior beyond the annotations.

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

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

The commit action is front-loaded and the notification and retry facts are useful, but the wording is dense with internal jargon ('private process custody permits', 'manage secret', 'independent scheduling grants') where plain language would carry the same meaning in fewer words.

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

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

For a destructive, open-world mutation with no output schema, the description covers the important behavioral facts (notification/cancellation, idempotent retry, recovery limits). It is still incomplete on what the 'scheduling grants' are, how failure is surfaced, and how this tool relates to the preview and cancel/reschedule siblings.

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

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

Schema description coverage is 0% with three required params, so the description carries the burden. It loosely maps the three fields to 'preview', 'hash' and 'confirmation reference' as distinct artifacts that must match the original preview, which clarifies their joint role, but it adds no format, validity or constraint detail beyond what the property names already 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 verb is 'Commit' and the object is a 'create preview', which implies finalizing a booking, but the phrasing is ceremony-laden rather than plainly naming the resource ('book a meeting'/'create a booking' never appears). An agent can infer it is the commit step of a two-phase scheduling flow but must decode jargon ('owner-confirmed create preview', 'independent scheduling grants') to be sure.

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

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

The description implies this is the commit that follows a preview step and gives one concrete scenario ('reuse the same preview, hash and confirmation reference after uncertainty'), which is real usage guidance. However, it never names the corresponding preview tool (e.g. preview_scheduling_action) or distinguishes itself from siblings like cancel_booking/reschedule_booking, so routing 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context the annotations lack: an authentication requirement and the semantic content of the result (including that 'incomplete outcome evidence' is surfaced).

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 the resource stated first, then the breakdown dimensions, then the auth note. Dense but no filler; a slight cost is that the em-dash list of labels is a bit 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?

For a one-parameter read-only stat tool with no output schema, the description usefully names the return dimensions and the auth prerequisite. Complete enough for an agent to invoke correctly; only the lack of sibling routing is a minor gap.

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

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

Schema coverage is 100% and the sole parameter (campaign_id) already documents that it is a Campaign UUID sourced from list_outreach_campaigns. The description adds nothing beyond the schema, so the baseline 3 for full coverage 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 resource and scope ('Pipeline-stage breakdown for one outreach campaign') and enumerates the exact fields returned (total/sent/active/won/lost, ratio, incomplete evidence). It is clearly distinguishable from a create/list tool, though it does not explicitly differentiate itself from the nearby outreach_analytics sibling.

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

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

The description implies usage by specifying it is scoped to a single campaign's pipeline stages, but it never states when to prefer this over outreach_analytics or the list_* siblings, nor any exclusions. 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 destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds specifics: the action "can notify the recipient," which is the concrete external side effect an agent should warn about, and it reinforces idempotent retry semantics. The obscure custody/secret sentence adds little usable behavior detail, but the notification disclosure is genuine added value.

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 is front-loaded in the first sentence and the passage is not bloated, but the final sentence ("Missing private process custody permits receipt recovery but cannot authorize a new dispatch; no manage secret is reconstructed") is deeply opaque and its value to an invoking agent is unclear.

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, open-world mutation with no output schema and no documented parameters, the description says nothing about success/failure outcomes or what state the booking ends in. It covers the essential preview-hash-confirmation triple and the notification side effect, but leaves the agent to infer the rest.

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

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

With 0% schema description coverage the description must carry parameter meaning, and it does reference all three inputs (preview, hash, confirmation reference) and ties them to the retry rule. It adds no format or provenance detail (UUIDs, SHA-256 hex, where the confirmation_id comes from), so the gap is only partially filled.

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 conveys that this commits a previously generated cancellation ("Commit the exact owner-confirmed cancel preview"), so the verb+resource are recoverable, but the phrasing is jargon-laden and never plainly says "cancels a booking." It also never names its sibling preview_scheduling_action, which is presumably where the preview is produced, so sibling differentiation is absent.

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 real conditional guidance: "Reuse the same preview, hash and confirmation reference after uncertainty," which tells the agent how to behave on retry. It also hints at a recovery path when the confirmation reference is missing. However, it never states the prerequisite (obtain a preview first) or contrasts with reschedule_booking/preview_scheduling_action.

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 substantial behavior beyond the annotations: the capture is immutable and owner-private, retries return the original capture even after source deletion, missing history stays unavailable, and the tool explicitly does not touch schedules, notifications or provider work. These are exactly the safety and idempotency details an agent needs for a write tool.

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

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

Four dense sentences, front-loaded with what is captured, then window default, then retry rule, then scope exclusions. Terminology is jargon-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?

For a 3-param write tool with no output schema and zero schema description coverage, the description covers immutability, idempotency, default window, and exclusions. It omits any indication of the returned capture shape and only indirectly names root_id's target, but no fatal gap remains.

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

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

Schema coverage is 0%, so the description must carry the load and largely does: it explains weeks (default eight UTC weeks, versus the 1-26 range in the schema) and request_id semantics (owner-wide idempotency key reused with identical arguments). root_id is only implied via 'one epic's current descendants' rather than stated as an epic identifier.

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/capture) and resource (immutable owner-private delivery scenario plus replay inputs scoped to one epic's descendants). The adverb 'Explicitly' hints at a contrast with an implicit sibling, but no sibling is named, so the agent must infer the get/list/compare distinction.

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

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

Gives real retry guidance ('reuse the same owner-wide request_id and exact arguments after an uncertain response') and a default window, which is useful operational context. However, it never says when to call this instead of list_feature_forecasts, get_feature_forecast, or compare_feature_forecasts.

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

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

Goes well beyond the annotations: it discloses the reserve-before-I/O pattern, that retrying the exact request_id returns the original cached result without a second provider call, the refusal conditions, and that unsupported/noncomparable values are surfaced as unknown rather than failing. It also scopes 'no remote writes or automatic reconciliation', which clarifies the meaning of the openWorld/readOnly annotations instead of contradicting them.

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

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

Roughly 65 words, front-loaded with the core action, then prerequisites, retry semantics, failure modes, and limits in priority order. Dense but nearly every clause carries distinct information; minor telegraphing ('Reserve before I/O') costs a little readability.

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

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

For a side-effecting, idempotent provider call with 0% schema coverage and no output schema, the description covers permissions, retry/replay, refusals, and unknown handling well. It is still incomplete on what the caller receives (the five field value shapes / unknown markers) and on the meaning of ticket_id and expected_revision values.

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

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

Schema description coverage is 0% for four required parameters, so the description must compensate. It does add meaning for request_id (idempotency/replay key) and hints at expected_revision via the stale-link refusal, but ticket_id and the provider enum are left entirely to the schema, leaving half the parameters unelaborated.

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

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

Names a specific verb+resource ('read five native fields for an existing owned link revision') and quantifies the scope as five fields, which an agent can distinguish from list/get siblings. The jargon 'owned link revision' is not defined, so it is clear but not fully self-contained.

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 real operational guidance: required permissions (integrations:read, tickets:write), when it refuses (changed link or credential), and how to recover (retry exact request_id/arguments). However it never says when to choose this over the many adjacent siblings (list_ticket_provider_fields, get_ticket_provider_field_request, list_ticket_provider_observations), so selection guidance is implied 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?

With readOnlyHint=false already declared, the description goes further and explains why: each deliberate check records new evidence (non-idempotent side effect) while the external read does not mutate provider state. It also discloses auth prerequisites (integrations:read, tickets:write), the absence of automatic recovery, and that unavailable or changed bindings remain unknown rather than falsely resolved.

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 is front-loaded and no sentence is purely filler, but phrasing like 'owner/link/configuration-bound observation' is jargon-dense and slows comprehension. The reconciliation caveat and the evidence/uncertainty note could be tightened into fewer clauses.

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, non-idempotent, open-world tool with no output schema, the behavioral envelope (permissions, side effects, uncertainty handling, reconciliation path) is well covered. The gap is parameter meaning: the description never clarifies the ticket_id/provider inputs or what the recorded observation contains.

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

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

Schema description coverage is 0%, so the description must compensate for ticket_id and provider, but it only implies the provider values (Jira/Linear) and says nothing about whether ticket_id is the internal UUID ticket or a provider-side issue key. The mention of an 'original effect ID' introduces a third identifier that is not even a parameter, adding potential confusion about what ticket_id means.

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

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

The description states a specific verb+resource: reading the linked Jira/Linear issue status while persisting a binding observation, which separates it from list_ticket_provider_observations and export_ticket_to_provider. It does not name a sibling tool outright, so differentiation is contextual rather than explicit.

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

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

It gives a clear situational workflow: inspect the observation and current evidence, then reconcile explicitly using the original effect ID. It also states the required scopes and that no automatic recovery happens, though it never names reconcile_ticket_provider_effect directly as the alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds real value: it enumerates what is reported, clarifies the interpretation rule (date drift alone is not worsening throughput), documents the noncomparable edge case, and explicitly states no attention reason or notification is created.

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 and followed by output, interpretation, and edge-case notes. Dense but nothing is redundant; each clause 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 does the work of explaining what is returned and how to read it, and it covers the noncomparable path and the absence of side effects. For a two-parameter read-only comparison tool this is close to complete, missing only the meaning of the two identifier parameters.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only indirectly does so via 'two owned saved delivery scenarios.' The earlier_id/later_id ordering and UUID format are left entirely to the schema and self-documenting names, with no added semantics such as chronological ordering requirements.

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 (replay and compare) and resource (two owned saved delivery scenarios), and the scope constraint (same cohort and window) sharpens it beyond a generic compare tool. It does not explicitly name sibling tools like get_feature_forecast or compare_scope_baseline to differentiate, so it stops short of a 5.

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

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

The description implies usage conditions: both scenarios must be owned and share the same cohort and window, and results are noncomparable otherwise. But it never states when to reach for this tool versus siblings such as get_feature_forecast or list_feature_forecasts, leaving the selection 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: 'Deleted/moved tickets remain visible; unknown estimates are not zero' and the permission requirement 'Requires tickets:read.' These are meaningful details an agent needs to correctly interpret the comparison results. There is no contradiction with annotations.

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

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

The description is two sentences with no filler. The main action is front-loaded, followed directly by the two key behavioral caveats and the permission requirement. 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 simple single-parameter read-only tool with rich annotations and no output schema, the description covers the purpose, ownership constraint, behavioral caveats, and required permission. It does not describe the output format or return shape, but that is not essential given the low complexity and the clarity of the comparison action.

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

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

The input schema has 0% description coverage and one required parameter, baseline_id. The description compensates by indicating that the baseline must be 'owned', which adds meaning to baseline_id beyond its name and UUID type. While not an explicit parameter description, the single obvious parameter and the 'owned baseline' qualifier are sufficient.

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

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

The description states a specific verb and resource: 'Compare an owned baseline with current scope, estimates and completion.' This clearly distinguishes it from sibling tools like get_scope_baseline or list_scope_baselines, which retrieve rather than compare, and from diff_portfolio_snapshots, which targets snapshots instead of baselines. The phrase 'owned baseline' adds a precise ownership scope.

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

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

The description provides useful context by specifying that the baseline must be 'owned' and that access requires 'tickets:read', but it does not explicitly state when to choose this tool over siblings or when not to use it. The use case is implied rather than directly contrasted with alternatives such as get_scope_baseline or diff_portfolio_snapshots.

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 safety and mutation semantics are covered structurally. The description adds that completion time is stamped or cleared and that only the caller's own tasks are affected, but says nothing about failure modes (e.g. unknown activity_id) or permission requirements.

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

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

Two tight sentences, front-loaded with the primary action and immediately following with the inverse path and the required field. 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 two-parameter mutation tool with no output schema, the description covers the primary action, the revert path and the required input. Only minor gaps remain: no error behavior and no mention of what the caller does with 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 50%: done already documents its true/false semantics and the description merely restates it, while activity_id is undocumented in both places beyond 'required'. The description adds no format or lookup guidance for activity_id, so it does not compensate for the coverage gap.

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

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

States a specific verb (mark done / reopen) against a specific resource (the caller's sales tasks/activities), and covers both directions of the operation. It is clearly distinguishable from list_sales_tasks and log_deal_activity.

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 done=false reopen path, which is useful usage guidance, but never states when to reach for this tool versus siblings like list_sales_tasks or log_deal_activity, nor any prerequisites such as ownership of the task.

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?

It adds key behavioral details beyond annotations: the result is a draft (not final/sent), it creates exactly one line item from the deal's amount, and client_name defaults from company/title. It doesn't discuss failure modes or permissions, but the draft status and defaulting behavior are useful for an agent.

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?

Single sentence with no filler; front-loads the action and immediately states the key mapping behaviors. Every phrase contributes.

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

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

The tool has 7 parameters and no output schema, and the description leaves five optional parameters semantically unexplained. It is sufficient for the minimal deal_id-only call but not for confident use of the full parameter set.

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 only 29%, so the description needed to explain the remaining parameters. It only clarifies deal_id (required, identifies the deal) and client_name (default), while notes, due_date, tax_rate, client_email, and payment_terms remain undescribed.

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'), a resource ('a draft invoice'), and a source ('from one of the caller's deals'), and clarifies scope with 'one line item' and default client_name. This distinguishes it from sibling create_invoice (blank invoice) and convert_lead_to_deal.

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 makes clear the intended input context: an existing deal belonging to the caller, with deal_id required. It does not explicitly name alternatives like create_invoice or when not to use, but the source constraint is enough to route selection in most cases.

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 profile is known. The description adds useful behavioral context beyond annotations: it specifies that the lead is advanced into the deal stage and that an already-closed lead is never downgraded. It does not detail permissions or full side effects, but it meaningfully supplements the safety signals.

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

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

The description is two tight sentences with the primary action front-loaded. Every clause adds value: the conversion action, the funnel advancement guard, the create_deal mirroring, and the required lead_id. There is no filler or repetition.

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

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

For a destructive 9-parameter mutation with no output schema, the description covers the core action and one important guard but omits most parameter details and does not explain what happens to the original lead after conversion. Annotations cover the safety profile, which helps, but the low schema coverage means the description should do more. It is minimally adequate but has clear gaps.

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

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

Schema description coverage is only 22%, so the description must compensate for undocumented parameters. It only states that lead_id is required and that optional deal fields mirror create_deal; it does not explain the stage enum, amount constraints, currency format, probability range, or expected_close_date. This leaves most parameter semantics to the schema, which itself is sparse.

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

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

The description states a specific verb and resource: convert an owned outreach lead into a deal and advance the lead into the deal stage. It distinguishes itself from siblings by naming create_deal and clarifying that optional deal fields mirror it while lead_id is required. An agent can identify the tool's core action 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 clearly implies usage for converting an owned outreach lead, and the 'mirror create_deal' note helps an agent choose between this tool and create_deal. It does not provide explicit when-not exclusions or prerequisites, but the context is strong enough to guide selection.

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

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

Annotations only say this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description goes far beyond: the run is private/encrypted and caller-owned, it "does not file taxes, move money, or send data to an external accounting service," historical runs stay unchanged, dropped rows fail silently with no partial-loss reporting, and hard caps (500 choices, 500 sources, 10,000 pairs, one active ingest per owner) are disclosed. No contradiction with 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?

Roughly several thousand words of engine parsing contract are inlined, and the actual purpose sentence does not appear until deep in the first paragraph. Much of the CSV delimiter/marker/splice minutiae is specification material rather than tool-selection or invocation guidance, drowning the signal an agent needs. It is topically grouped but grossly over-sized.

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

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

For an 8-parameter, nested-schema, no-output-schema tool, the description is remarkably complete: it explains the result total semantics ("counts classified spend only"), names the catalog channels (scope_review, errors, notices) an agent must inspect, and covers the silent-failure and whole-file-loss cases. Nothing material is left for the agent to infer about correct invocation.

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

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

With 63% schema coverage, the description adds real meaning: scope requires exactly one entity and tax_year with inclusive period bounds inside that year; scope_assignments are keyed by source document and original record number, with record null for raw receipts; conflicting observations need a review_note; duplicate_resolutions decisions and the counted_source requirement are explained; context_text is a PARTIAL gate. It omits any mention of marginal_rate.

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 does state the specific action and resource: "Analyze supported textual accounting records with the pinned deterministic Writeoff engine and create a private, encrypted audit run owned by the caller." However, this core purpose is buried mid-paragraph after scope-requirement prose, and sibling differentiation is thin — only preview_accounting_ticket_sync is named, with no contrast against get_accounting_run/list_accounting_runs/delete_accounting_run.

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 routing advice in places: "Use preview_accounting_ticket_sync to turn those residuals into reviewable work," "Use replaces_run_id for a scoped correction," and "Submit runs one at a time: one ingest is active per owner at a time." It covers when-to-use contexts but never states when NOT to create a run versus the other accounting-run siblings.

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

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

Annotations already mark this as non-read-only and non-idempotent, so the description's main job is to add context. It adds that the operation creates a durable, owned record and requires the comparisons:write permission, which goes beyond what the annotations alone convey. There is no contradiction with the annotations.

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

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

The description is short and front-loaded, with the core action in the first clause and permission appended in a second sentence. The phrase 'usually one a comparison just created' is slightly awkward and hurts readability, but there is no redundant or filler content.

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 three-parameter creation tool with no output schema, the description conveys the main purpose, ownership constraint, and auth requirement. It does not clarify what a 'durable comparison' means, what the response contains, or how to source the three session IDs, leaving moderate gaps for an agent to resolve.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain set_id or map 'member run' to baseline_session_id clearly. 'Candidate run' aligns with candidate_session_id, but the description leaves the relationship between the terminology and the schema largely implicit.

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 identifies a specific action ('Record one durable comparison') and resource (a comparison artifact), and the ownership qualifier adds useful scope. It does not explicitly differentiate itself from siblings like run_comparison or create_comparison_verdict, but the persistence-oriented wording makes the intent reasonably clear.

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

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

The phrase 'usually one a comparison just created' gives a temporal hint about when to use the tool, and 'you own' implies an eligibility condition. However, it is ambiguous and does not state when not to use it or name more appropriate sibling tools such as create_comparison_verdict or run_comparison.

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 supply no positive hints, so the description carries the behavioral burden. It clearly discloses the append-only membership behavior, the inability to adjust fixtures after results are seen, and the required permission. Core mutation semantics are transparent.

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, each earning its place: the first states the purpose, the second flags the critical immutability constraint and permission requirement. No filler or repetition.

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

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

For a low-complexity create tool with a single parameter, the description covers purpose, permission, and the main behavioral risk. It could mention the return value, but that is not essential for calling the tool correctly.

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

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

The schema documents the single required name parameter with length constraints, but schema_description_coverage is 0%. The description adds no further meaning for the parameter, though the parameter is simple and self-descriptive.

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

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

States a concrete action and resource: it creates an empty owned collection for comparison. The phrase 'to measure against' clarifies the domain role, distinguishing it from sibling comparison tools like create_comparison_artifact and create_comparison_verdict.

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

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

No explicit when-to-use or alternative routing is given. It implies use when a new comparison set is needed, but it doesn't mention add_comparison_runs for populating the set or explain how it differs from create_comparison_artifact/create_comparison_verdict.

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

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

The description adds valuable behavior not present in annotations: an undecided result records nothing and is reported instead, and the operation requires comparisons:write permission. With readOnlyHint=false this is consistent with a write operation, and the no-op behavior is a meaningful transparency gain despite not detailing return format or idempotency.

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

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

Two compact sentences front-load the core purpose and immediately add decision-rule and no-op behavior. Every sentence earns its place; the permission requirement is efficiently appended.

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

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

The description covers the essential no-op case and permission requirement, which is useful with no output schema present. However, it does not describe the format of the reported result, the defaults behind the default decision rule, or the meaning of required set_id, leaving moderate ambiguity for an agent invoking the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely maps to parameters: 'comparisons you name' hints at artifact_ids and 'thresholds you state' covers thresholds. The required set_id is not mentioned, and the threshold object's min_decisive, min_improved, and max_regressed fields are left unexplained.

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 a specific action ('Record an accept or reject call') and resource ('comparisons you name'), with additional detail about decisions and thresholds. It differentiates from nearby comparison-set/artifact creators by focusing on recording a verdict, though it does not explicitly name or contrast with siblings like run_comparison.

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 intended use is implied: you record a verdict over named comparisons under default or stated thresholds. However, there is no explicit guidance about when to choose this tool over run_comparison, get_comparison_verdict, or create_comparison_set, and no exclusions or alternative conditions are 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 indicate this is a non-readonly, non-idempotent, non-destructive operation. The description adds no extra behavioral context such as whether duplicate names are allowed, whether creation can fail on duplicates, or what happens after creation.

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

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

The description is a single concise sentence with no filler and is front-loaded. However, it is so minimal that it does not earn its place for a tool with seven parameters and no other explanatory material.

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

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

The description only covers the core action and scope. It lacks guidance on required fields, parameter meanings, validation behavior, or expected outcomes, and there is no output schema to compensate. An agent would have to infer most usage details from parameter names.

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

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

Schema description coverage is 0%, and the description does not mention any parameters, including the required 'name' field. The tool's seven parameters are left entirely to the agent to interpret from names and types alone, which is insufficient for a create operation.

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

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

The description states a specific action ('Create') and a clear resource ('consulting client'), plus a scoping qualifier ('account-private'). This distinguishes it from related resources like create_consulting_engagement and from update/list variants, though the meaning of 'account-private' is not explained.

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

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

No guidance is provided on when to use this tool versus alternatives such as update_consulting_client or list_consulting_clients. The intended context is only implicit from the name and resource type.

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 indicate it is not read-only, not idempotent, and not destructive, but the description adds a meaningful nuance: 'internal draft' implies the deliverable is not final or client-facing. However, it does not disclose permission requirements (what 'owned' entails), side effects of creation, or any other behavioral details. The description adds some value beyond annotations but remains thin.

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

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

The description is a single, compact sentence that front-loads the action ('Create') and the key qualifiers ('internal draft deliverable', 'owned engagement'). There is no filler or redundancy; it is as concise as possible while still conveying basic purpose.

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

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

Given the tool has 6 parameters (3 required), no output schema, and generic annotations, the description is far too brief to be complete. It does not explain the meaning of 'internal draft', the concept of 'owned engagement', or any expected behavior. An agent would struggle to decide when to use this tool versus alternatives like 'update_consulting_deliverable' or 'create_consulting_document_revision'.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of param explanations. It only hints that 'engagement_id' relates to an 'owned engagement', but does not clarify the required 'key' (a pattern string) or 'title', nor the optional fields. Since the schema provides no descriptions at all, the tool description leaves the agent with almost no semantic guidance for parameters.

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

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

The description clearly states a specific verb ('Create') and resource ('internal draft deliverable'), and adds context ('on an owned engagement'). This distinguishes it from sibling tools like 'approve_consulting_deliverable' or 'submit_consulting_deliverable' by hinting at a draft state, but it does not explicitly name any alternative or contrast. It is not a tautology and conveys the main purpose effectively.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or contexts (e.g., 'Use when the engagement is owned by you and a draft is needed'). No exclusions or sibling references are included, leaving the agent to infer usage from the name alone.

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

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

The description adds behavioral context beyond annotations by introducing 'revision-safe' and 'owned engagement,' hinting at optimistic concurrency and ownership requirements. It does not disclose conflict behavior, what happens on revision mismatch, or the response format, but the annotations already communicate write intent via readOnlyHint=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?

A single, front-loaded sentence with no filler. Every phrase ('revision-safe', 'proposal or SOW draft', 'owned engagement') carries meaningful information about the operation.

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 tool with five parameters, no output schema, and weak structured metadata, the description is too sparse. It does not explain the revision-safety mechanism, the expected_latest_revision parameter, or the semantics of title/body, leaving an agent to guess important invocation details.

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

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

With 0% schema description coverage, the description must compensate, but it only weakly maps to parameters: 'proposal or SOW' corresponds to the kind enum and 'owned engagement' hints at engagement_id. It does not explain title, body, or expected_latest_revision, which is especially important for a 'revision-safe' tool.

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

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

The description states a clear verb and resource: 'Create a revision-safe proposal or SOW draft on an owned engagement.' It names specific document types (proposal/SOW), distinguishes this from update/approve siblings, and matches the tool's core function.

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 'on an owned engagement' implies a prerequisite/ownership condition and 'revision-safe draft' implies creation of a new revision. However, it does not explicitly state when to use this tool versus update_consulting_document_revision or approve_consulting_document_revision, leaving usage guidance mostly 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 indicate this is a mutation (readOnlyHint false) and not destructive. The description adds no additional behavioral context, such as side effects, required permissions, or relationships established with the client.

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

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

The description is a single sentence with no redundant words, effectively front-loaded. However, its brevity borders on under-specification, which slightly detracts from this dimension.

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 tool with 9 parameters, no output schema, and minimal annotations, the description is inadequate. It fails to explain the concept of an engagement, preconditions, or expected behavior, leaving significant gaps for an agent to fill.

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

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

Schema description coverage is 0%, so the description fails to explain any parameter semantics beyond what the schema's names and types imply. It does not clarify fields like accounting_run_ref or sales_deal_ref, leaving the agent to guess their purpose.

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

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

The description states a clear action (create) and a specific resource (consulting engagement), and distinguishes it from related tools like create_consulting_client and create_consulting_deliverable. The qualifier 'owned' is ambiguous but does not obscure the primary purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any conditions or exclusions. It does not mention that the client must already exist or be 'owned', nor does it point to update_consulting_engagement for modifications.

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 indicate readOnlyHint=false and destructiveHint=false, so the description's clarification that it is a create operation adds value. However, it does not disclose side effects such as whether the asset is immediately visible or requires approval. The emphasis on 'private draft' and 'no publish/send' is useful but not exhaustive.

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

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

The description is two sentences, succinct, and front-loads the key concept of creating a draft. It avoids unnecessary detail, making it easy to scan.

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

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

Given the tool's moderate complexity (7 parameters, no output schema), the description could include more about expected side effects or validation rules. It does not mention that the asset is private (which is helpful) or clarify the relationship with approval workflows (e.g., approve_content_asset). The presence of required campaign_id is hinted but not explained. Overall, adequate but not exhaustive.

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

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

With only 14% schema description coverage, the description's mention of 'private draft' and 'content asset' adds context to parameters like title, content, and asset_type. However, it does not explain individual parameters like channel or scheduled_for, leaving the agent to infer their meaning from schema names. The additional context is valuable but not comprehensive.

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 that the tool creates a private draft content asset and emphasizes that there is no publish/send operation. This is specific and actionable, and while it doesn't explicitly compare to siblings like create_content_asset_revision or update_content_asset, its distinct purpose is clear.

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

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

The description implicitly conveys that this tool is for creating a draft, not for publishing, but it does not explicitly state when to use this tool versus update_content_asset or create_content_asset_revision. The distinction from revision creation is implied but not explicitly stated, which is a minor gap.

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

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

The description clarifies that the operation creates a new owned draft revision rather than modifying the frozen one, which aligns with and slightly extends the annotations (readOnlyHint=false, destructiveHint=false). It does not disclose side effects, whether the source revision is preserved, or what the new revision's status will be beyond 'draft'.

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

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

The description is a single, well-structured sentence that front-loads the core action and source state. It is concise with no filler, though it could have included more operational context without becoming bloated.

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 7 parameters, no output schema, and no parameter guidance, a one-sentence description is insufficient for an agent to invoke this tool confidently. It lacks information about required fields beyond asset_id, how the revision relates to the asset, what happens upon creation, and what response to expect.

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

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

Schema description coverage is only 14%, and the description provides no parameter-level guidance. It does not explain the meaning of title, channel, content, asset_type, scheduled_for, or revision_notes, nor does it clarify that asset_id must be a full UUID beyond what the schema already 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?

The description names a specific verb ('create'), a specific resource ('owned draft revision'), and a clear source state ('frozen submitted/approved/rejected revision'). This meaningfully distinguishes it from sibling tools like create_content_asset or update_content_asset, though it does not explicitly name those alternatives.

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

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

The phrase 'from a frozen submitted/approved/rejected revision' implies the tool is used when an existing revision is in a terminal state and a new draft branch is needed. However, it does not explicitly state when not to use it or mention alternative tools such as update_content_asset, leaving the usage context somewhat 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?

Beyond the annotations (readOnlyHint false, destructiveHint false), the description adds meaningful behavioral context: the deal 'appears live on the owner's Sales board' and 'No deletes are exposed over MCP.' This clarifies immediate visibility and the absence of a delete operation, which is helpful for the agent's expectations.

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

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

Three sentences, each with a distinct purpose: core action, parameter guidance, and behavioral note. There is no fluff, and the most important information is front-loaded. The description is appropriately sized for the tool's complexity.

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 10 optional parameters and no output schema, the description covers the essential runtime behavior (live board visibility, no deletes, ownership) and the critical title/lead_id relationship. It does not explicitly state the mutual exclusivity or what happens if both are provided, but the schema and description cover enough for an agent to correctly invoke 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 80%, so the baseline is 3. The description adds value by clarifying the relationship between title and lead_id (one is needed, lead_id inherits the lead's company/name as title) and emphasizing caller ownership. This goes beyond the schema's individual field descriptions, justifying a 4.

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

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

The description clearly states the tool creates a sales deal owned by the caller, which is a specific verb+resource. It is distinguishable from siblings like update_deal, convert_lead_to_deal, and create_invoice, though it does not explicitly name them. The ownership detail adds useful differentiation, but a direct sibling comparison would make it a 5.

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

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

The description gives some parameter guidance ('Provide a title, or a lead_id...') and notes the deal appears live, but it does not explicitly explain when to use this tool versus alternatives such as convert_lead_to_deal for lead conversion or update_deal for modifications. The context is implied rather than explicit, so no strong 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?

The description discloses behavioral traits beyond annotations: ownership by the caller, server-side computation of totals from line_items and tax_rate, and the initial 'draft' status with a clear state transition. Annotations only indicate it is not read-only and not destructive, so the description adds meaningful 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?

The description is two sentences with no redundancy. Purpose and constraints are front-loaded, and the behavioral notes are packed efficiently. 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 creation tool with no output schema, the description covers the essential facts: what is created, ownership, optional additions, computed totals, initial status, and the next step. Minor gaps (e.g., behavior with no line items, validation of client_name) are not critical 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 56%, and the description enhances meaning for deal_id, line_items, and tax_rate (linking, seeding, and total computation). However, it does not clarify notes, client_email, or provided payment_terms beyond what the schema already mentions (e.g., examples). It adds some value but does not fully compensate for the undocumented parameters.

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

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

The description states a specific verb ('create'), a distinct resource ('draft invoice'), and key constraints ('owned by the caller for a client', 'optionally seeded with line items and linked to an existing deal'). It clearly distinguishes this creation tool from sibling tools like update_invoice, send_invoice, or convert_deal_to_invoice.

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

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

The description gives clear context: this tool creates a draft invoice stub. It explicitly routes the next step ('call send_invoice to mark it sent'), which provides workflow guidance. However, it does not name alternatives like update_invoice for existing invoices or convert_deal_to_invoice for converting a deal, so it lacks explicit exclusions.

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 signal a write operation, so the bar is lower. The description adds useful behavioral context: owner-private and reusable. However, it does not disclose duplicate handling, idempotency implications, required permissions beyond ownership, or what the created definition entails.

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

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

The description is a single front-loaded sentence with no filler; every word adds meaning. It is appropriately concise, though the brevity comes at the cost of explanatory depth.

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, minimal annotations, and four undocumented parameters, the description needs to carry more contextual weight. It covers privacy and reusability but omits return behavior, relationship to channels/pain_points, and practical invocation details, leaving the agent under-informed.

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

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

Schema description coverage is 0%, so the description should compensate for the four parameters, but it does not explain how 'name', 'channels', 'description', or 'pain_points' are used or constrained. The parameter names are somewhat self-evident, but the description adds no semantic value beyond the schema.

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

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

The description states a specific verb ('create'), resource ('marketing audience'), and two distinguishing constraints: owner-private and reusable. This clearly differentiates it from get/update/list siblings and from create_marketing_campaign/create_marketing_brand.

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 'owner-private reusable audience definition' implies a use case, but the description gives no explicit when-to-use/when-not-to-use guidance, no prerequisites, and no comparison with alternatives such as update_marketing_audience. Usage is implied 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 declare non-readOnly, non-openWorld, non-idempotent, non-destructive, which doesn't reveal much. The description adds the permission requirement and the 'owner-private' nature, which is useful. However, it doesn't disclose side effects, return value, or any constraints beyond creation. Given annotations are minimal, the description carries more burden but still falls short of 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?

The description is one short sentence plus a permission note, very concise. It front-loads the core action and uses no extraneous words. However, it is so brief that it misses important information, though that's more of a completeness issue than conciseness.

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

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

For a create operation with no output schema, the description should explain what happens (e.g., returns created brand, any side effects). It also fails to describe parameters or usage scenarios. Given the tool has 4 parameters and zero enrichment, the definition is incomplete for an agent to invoke correctly without further inference.

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

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

Schema description coverage is 0%, meaning the description does not explain parameters. The schema has name (required), voice, guidelines, and value_proposition, but the description provides no guidance on what these mean or how they relate to brand creation. This is a significant gap since the description must compensate for low 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?

The description states a specific verb ('Create') and resource ('brand identity'), and clarifies it is 'owner-private', distinguishing it from related siblings like create_marketing_audience or create_marketing_campaign. The purpose is unambiguous.

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

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

The description provides clear context that this creates a brand identity and specifies a required permission (marketing:agent_write). It does not explicitly mention when not to use it or name alternatives, but the 'owner-private' qualifier gives enough context for typical use cases.

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 this is a mutating operation (readOnlyHint=false). The description adds the ownership constraint and 'owner-private' context, but does not disclose return behavior, error cases, or side effects beyond that. Some value added but not rich behavioral disclosure.

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

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

A single sentence that is front-loaded with the core purpose and key constraints. No 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 create tool with 8 parameters and no output schema, the description is sparse. It does not explain the return value, the meaning of each field, or prerequisites (e.g., needing to create a brand/audience first). The ownership constraint is mentioned, but much is left implicit.

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 low (25%), with only brand_id and audience_id described as 'Full UUID from the matching list tool'. The description adds meaning by explaining the linking constraint ('linked only to owned brand/audience ids'), but does not clarify the other six parameters (e.g., status, channels, objective). It partially compensates but not fully.

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

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

The description states a specific verb (create) and resource (marketing campaign) and adds the scoping constraints 'owner-private' and 'linked only to owned brand/audience ids'. This clearly differentiates it from sibling tools like create_marketing_audience and update_marketing_campaign.

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 implies when to use: when creating a new campaign with owner-private visibility and linking to owned ids. However, it does not explicitly state when not to use alternatives or mention prerequisites like obtaining brand/audience ids from list 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 are minimal (readOnlyHint false, destructiveHint false, etc.), so the description carries responsibility. It discloses the costly behavior of start_workflow ('spends the account's credits unattended') and that cooldown is the only bound, plus persistence ('survives the conversation'). It also states authentication, account tier, and scope requirements. These go beyond the annotations and give the agent a realistic expectation of side effects.

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 three sentences with zero fluff. The core purpose is front-loaded in the first sentence, followed by the key benefit and persistence trait, then a necessary cost warning. Every sentence adds value; there is no redundant phrasing or repetition of schema property names.

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

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

The tool is complex (8 parameters, nested action_config, 5 required) and has no output schema, so the description needs to cover the overall behavior and important context. It explains the trigger logic, persistence, costs, and prerequisites. It does not mention the return value (e.g., a monitor ID), but since there is no output schema, the description is not required to; still, a brief hint about the returned object would make it fully complete. Given the strong schema coverage and sibling presence, a 4 is appropriate.

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 every parameter. The description adds a conceptual mapping ('a count you name' → subject, 'a line you set' → threshold, 'do the thing you chose' → action) but does not add syntactic details or edge-case notes beyond the schema. With full schema coverage, a score of 3 is the appropriate baseline; the description adds marginal clarifying context.

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

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

The description states a specific verb and resource: 'Save a standing watch' which is the monitor, and explains its function clearly ('fires later, on its own: when a count you name crosses a line you set'). It distinguishes from siblings like list_monitors and delete_monitor by focusing on creation and persistence across conversations. The purpose is unambiguous and does not restate the tool 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?

The description provides clear context for when to use the tool: to 'bank a condition and stop polling for it', implying this replaces manual polling. It also notes the watch 'survives the conversation', so it's for long-lived checks. It does not explicitly name alternative tools or give when-not-to-use conditions, but the contrast with polling and the distinct lifecycle make the usage clear enough.

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 set hints to false, so they provide little behavioral detail. The description adds meaningful context: the operation is reversible via the dashboard, requires authentication, and returns a campaign id. This exceeds the structured annotation coverage without contradicting it.

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 deliver the core purpose, return value, reversibility, and authentication requirement. It is front-loaded with the main purpose and contains 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 simple flat create operation with fully documented parameters, the description covers the essential behavioral aspects: ownership, return value, reversibility, and auth requirement. 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 description coverage is 100%, and each parameter already has a clear description. The tool description does not need to add parameter details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool creates a new outreach campaign and adds specifics: it is owned by the authenticated user and returns the new campaign id. The verb+resource is unambiguous, though it does not explicitly contrast with sibling tools like create_marketing_campaign or create_outreach_pitch.

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

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

The description implies when to use it: when a user wants to create an outreach campaign owned by themselves. It does not state when to prefer an alternative or mention exclusions, so the routing guidance is only 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 are all false, indicating no read-only, idempotent, or destructive hints, but the description clearly states it creates a resource and requires authentication. It adds provenance stamping and return of pitch id, which is useful beyond annotations. However, it doesn't disclose details like ownership implications or whether duplicate names are allowed.

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

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

The description is concise, with three sentences that state the function, key structural elements, ownership, provenance, return value, and authentication requirement. No fluff, and important details are front-loaded.

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

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

For a creation tool with full schema coverage and no output schema, the description provides necessary context: ownership, provenance, return value, and auth. It could mention what happens on duplicate names or whether the tool is idempotent, but given the tool's simplicity, this is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds the purpose of the templates but doesn't add detail on the 'prompt' parameter's relationship to drafting. Baseline 3 is appropriate because the schema carries the load.

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 that it creates a reusable pitch template with subject and body templates, owned by the user. It distinguishes itself from related tools like create_outreach_campaign by focusing on templates, though it doesn't explicitly name a sibling to differentiate from.

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

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

The description implies usage when a reusable pitch template is needed, and notes provenance and authentication requirements. However, it does not explicitly state when to use this over create_outreach_campaign or draft_outreach_email, or provide exclusions.

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 substantial behavioral context beyond annotations: anyone with the link can read it, copied content cannot be recalled, approval and permission requirements, UTC Z expiry bounds, public visibility acknowledgment, uncertain-reply handling, and the fact that no link is sent. This is rich disclosure for a security-sensitive mutation tool.

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

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

Front-loads the purpose and then layers risk, prerequisites, constraints, recovery, and delivery expectations. The density is justified for a high-risk share-creation tool, though some statements could be tightened.

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 safety, approval, expiry constraints, recovery, and the fact that no link is sent. However, with no output schema and zero schema description coverage, it leaves snapshot_id and expected_projection_hash underspecified and only implies what the create response contains.

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

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

Schema coverage is 0%, so the description must compensate for all five required parameters. It explains expires_at format and range, acknowledge_public, and request_id retention, but does not explain snapshot_id or clearly identify expected_projection_hash as the previewed projection hash. Partial compensation for a zero-coverage 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: create an expiring read-only bearer link for the exact previewed report projection. This distinguishes it cleanly from sibling tools such as preview_portfolio_report_share, get_portfolio_report_share, and revoke_portfolio_report_share.

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 prerequisites and context: requires explicit reports:share and independent human approval, expiry bounds, explicit public acknowledgment, and recovery guidance via get_portfolio_report_share_receipt. It stops short of explicitly naming preview_portfolio_report_share as a required predecessor or stating when not to use the 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?

Beyond the annotations (which already declare non-read-only, idempotent, non-destructive, closed-world), the description discloses the default paused state, that captures are internal only ('No email or provider calls'), the active-ticket aggregate semantics, and the auth requirement. The retry guidance ('preserve request_id and exact intent') adds practical idempotency context that annotations alone don't convey.

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

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

Front-loaded with the core purpose, then progressively narrower details (default state, aggregate semantics, project_id scope, side-effect limits, retry, permission). Dense but each sentence adds information; only slight redundancy in restating project_id scope.

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 a nested-object schema, no output schema, and no parameter descriptions, the description supplies default state, side-effect boundaries, permission requirement, and idempotent-retry guidance. It covers enough for correct invocation, though the scheduling fields (hour/minute/timezone) remain undocumented.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the meaning of frequency (daily/weekly/monthly), the enabled default (paused), and project_id scope, but the nested fields hour, minute, timezone, weekday, and monthday are left entirely to the schema. Partial compensation only.

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

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

The description states a specific verb and resource ('Create an owner-private ... portfolio report schedule') plus the frequency scope (daily/weekly/monthly). This is clearly distinct from siblings such as create_portfolio_snapshot, create_portfolio_report_share, and update_portfolio_schedule.

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 operating context: schedules default to paused and must be explicitly enabled to start captures, and project_id should come from project_list. It also states the prerequisite ('Requires tickets:write'). It does not explicitly contrast with update_portfolio_schedule or list_portfolio_schedules, so it stops short of full when/when-not 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 only tell us it is a non-destructive write; the description adds substantial context beyond that: immutability, no recompute, cannot be edited or deleted, records the capturing credential for attribution, and requires auth plus the tickets:write scope. This is rich disclosure the structured fields 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 sentences, front-loaded with the core action and scope, then rationale then immutability then auth. Every sentence earns its place, though the immutability point is restated ('fixed at this moment and never recomputed' plus 'cannot be edited or deleted'), which is minor 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?

There is no output schema, but the description explains what a snapshot contains (totals by status and priority) and the lifecycle constraints an agent must know before calling. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description reinforces the project_id scope semantic (single project vs whole portfolio) but adds no format or syntax details beyond the schema, so the 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 (capture) and resource (immutable rollup snapshot) plus scope distinctions: YOUR OWN portfolio vs a single owned ProjectWorkspace when project_id is supplied. It names the sibling diff_portfolio_snapshots and its relationship, so an agent can distinguish this from list/get/create_note/export 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 explicit timing guidance ('capture one before a review rather than after') and explains the alternative it pairs with (diff measures movement against a prior snapshot). It also routes scope selection (project_id vs whole portfolio), leaving little 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?

Goes well beyond the annotations (readOnly=false, idempotentHint=false, destructive=true-not-set) by disclosing that a lost reply may have committed, there is no replay key, and the write must not be auto-retried. It also states the auth and tickets:write scope requirement and that nothing downstream gates on the note.

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?

Multiple tight sentences with the core action front-loaded and the hash-check rationale following immediately. Dense but nearly every clause carries operational meaning; slightly long for a single write tool.

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

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

With no output schema, the description still covers the safety-relevant behavior an agent needs: auth/scope, retry hazard, refusal semantics, and the no-gating guarantee. Nothing material to invoking 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 semantics: it explains why expected_content_hash exists (revision assertion) and what happens when it is omitted. It adds value beyond the schema's 'a mismatch is refused' by clarifying the omission path.

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 (record) and resource (portfolio snapshot note) and scopes it to the user's own snapshots. It is immediately distinguishable from siblings like list_portfolio_snapshot_notes (read) and create_portfolio_snapshot (creates the snapshot itself, not a note).

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 it to record a decision/comment, and it explicitly does not approve/reject/block. It explains the conditional behavior of expected_content_hash (pass it to assert revision, omit it to merely record). It stops short of naming a specific alternative tool, so it falls just below 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 write, idempotent, non-destructive, closed-world; the description independently adds the required scope ('Requires tickets:write') and retry semantics (retain request ID after an uncertain reply), which is meaningful operational context beyond the hints. It does not explain what the envelope contains or how it can later be inspected.

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, front-loaded sentences with no filler; the freeze semantics come first, then constraints, then the operational caveat. Dense rather than bloated, though the telegraphic style costs some clarity.

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 non-destructive, idempotent write with no output schema, the description covers auth and retry behavior, but it leaves the core semantics of the envelope's fields (hash and schema version) undocumented, so an agent cannot verify it is passing the right values.

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

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

Schema coverage is 0% for four required parameters. Only request_id gets any narrative treatment (via the retry guidance); snapshot_id, expected_source_hash, and especially the 1-4 expected_source_schema enum are left entirely unexplained, and the enum's meaning is exactly the thing an agent cannot guess.

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 verb is 'Freeze' and the object is 'verified saved values with the definitions and disclosures shown now', which hints at a snapshot-with-provenance operation but never plainly says it creates a durable 'report review envelope'. A reader can infer the general shape but not cleanly distinguish it from create_portfolio_snapshot or create_scope_baseline at a glance.

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 clear usage constraint ('Original-capture definitions are unavailable') and an explicit exclusion scope ('this does not approve, share or hold data'), plus a recovery rule ('keep the exact request ID and fields after an uncertain reply'). It stops short of naming alternative tools, but the when/when-not framing is solid.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive mutation. The description adds real behavioral context beyond that: it requires authentication and the tickets:write scope, the view is private until shared, and it stores the query rather than results so it re-runs live. It omits any note on failure/revision conflict, though that lives in the schema's expected_revision field.

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 purpose, then adds three short, distinct and useful clarifications (query-not-results, private-by-default, auth/scope). Every sentence carries a distinct fact 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 complex 8-parameter tool with nested objects and no output schema, the description covers auth, privacy, and the live re-run semantics well. It does not address the revision/conflict workflow, but that requirement is documented on expected_revision in the schema, so the gap is minor.

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

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

Schema description coverage is 100%, so the parameters are largely self-documenting and the baseline is 3. The description adds conceptual framing ('saves the QUESTION, not an answer') that clarifies the intent of the filters object, but gives no field-level meaning beyond what the schema already carries.

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 named ticket filter/column/grouping/sort bundle), which is far more precise than the bare name. It doesn't name the neighboring operations (update_saved_view, execute_saved_view, share_saved_view) explicitly, though 'reopen it later or share it with a team' implies the create-vs-use-vs-share boundary.

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

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

Usage is implied rather than stated: the reader infers you call this to persist a new view, but there is no explicit when-to-use versus update_saved_view (modify an existing view) or execute_saved_view (run it). No exclusions or preconditions for choosing this tool over its siblings are given.

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

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

The description carries the behavioral burden because annotations are all generic false hints. It discloses immutability, request_id-based retry/new-baseline semantics, and the required permission, which materially informs an agent about side effects and prerequisites.

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

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

Three sentences with no filler: primary action, retry behavior, then auth requirement. The most important information is front-loaded.

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

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

The description covers action, safety, retry, and auth, but no output schema exists and root_id/label semantics are incomplete, so an agent still has to guess at two required inputs and the response shape. Adequate but with clear gaps.

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

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

Schema coverage is 0% and only request_id is semantically explained via the retry/new-baseline guidance. root_id is only indirectly tied to 'an owned delivery group', and label is not explained at all, leaving two required parameters under-specified.

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 'Save immutable scope, estimates and explicit plan versions/dates', a specific verb and resource with clear object and ownership scope. It is immediately distinguishable from sibling get/list/compare_scope_baseline 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?

It gives actionable guidance: use for an owned delivery group, reuse the same request_id on retries, and require tickets:write. It does not explicitly name alternative tools or state when not to use it, 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?

Adds substantial context beyond the annotations: the required authentication and workflows:write scope, that the saved definition matches the web builder's, that the slug is derived from the name and returned, and the execution semantics (dependency order, bounded parallel layers, list order, and the routed next_step/quality_gate path that cannot mix with depends_on).

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 slug/run_workflow handoff are front-loaded, and each sentence conveys usable information. It is dense and runs long, but no sentence is filler given the tool's complexity.

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 supplies the missing return information (the derived slug) and covers auth requirements, execution model, and the routing rules an agent needs to author a valid definition. Complete for this tool's complexity.

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

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

Schema description coverage is 100% and the nested step schema is extremely detailed, so the schema carries the parameter burden. The description reiterates the depends_on vs routed-fields exclusivity and the slug derivation, but adds little syntax or format detail beyond what the schema already 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?

Opens with a specific verb+resource ('Create a new custom workflow template the caller owns') and adds the scope of what it produces. It clearly distinguishes itself from siblings such as update_workflow_template, plan_workflow, and run_workflow by naming the creation act and the slug handoff.

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 the use case ('built in conversation instead of by hand in the browser') and routes the agent forward to run_workflow with the returned slug. It does not, however, contrast against peers like plan_workflow or explain when to use this versus updating an existing template.

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

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

Goes well beyond the annotations by disclosing that approve and amend both incur billing, that amend requires notes because it re-runs the step, that the tool errors loudly rather than no-opping on a stale run, and that authentication plus the workflows:approve scope are required. This is exactly the extra context annotations cannot carry.

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

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

Four short sentences, front-loaded with the core action, then the amend caveat, the cost/error behavior, and the auth requirement. No filler and nothing buried behind preamble.

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 non-idempotent, money-spending mutation with no output schema, the description supplies everything an agent needs to call it safely: id source, decision semantics, notes requirement, billing impact, stale-run behavior, and required scope.

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 enum meanings, the notes maxLength, and the notes-required-for-amend rule are already documented in the schema. The description restates those semantics with slightly more workflow framing but adds little the schema does not already say.

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 ('answer a waiting checkpoint by request id') plus the three enumerated actions, which is exactly what an agent needs to distinguish this from the sibling list_approvals and from generic workflow tools like advance_workflow.

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 triggering context (a waiting checkpoint), the source of the id ('from list_approvals'), and the failure condition when the run is no longer waiting. It does not explicitly name a when-not alternative, but no sibling competes for this action, so 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?

Adds substantial value beyond annotations: it explains that data and provenance are retained, that the action is reversible via restore_accounting_run, that it is not permanent erasure, and that no external service is contacted. This explains why destructiveHint=false and idempotentHint=true apply rather than merely restating them.

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

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

Four short sentences, front-loaded with the core purpose, and each sentence carries distinct semantics (reversibility, idempotency, isolation). The final two sentences partially echo the idempotentHint and openWorldHint annotations, which is mild redundancy but still confirms behavior in prose.

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 tool with no output schema, the description covers the essential behavioral facts an agent needs: scope of effect, reversibility, idempotency, and lack of external calls. 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 coverage is 50%: expected_revision carries its own 'refuses a stale visibility change' description in the schema, while run_id is self-evident (uuid of the run). The description adds no parameter-level detail, so the baseline of 3 appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Hide one owned Accounting run') and immediately reframes delete semantics as a soft hide from lists and reads, distinguishing it from a permanent-erasure tool. An agent can identify what it does and how it differs from the sibling restore_accounting_run 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?

Clarifies the soft-delete semantics and explicitly names restore_accounting_run as the reversal, which routes the agent to the correct sibling when undoing. It stops short of stating explicit when-to-use / when-not-to-use conditions or prerequisites, so it is clear context rather than full conditional 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 declare destructiveHint=false, which could be surprising for a delete tool. The description clarifies this by stating 'Does not touch anything it already started,' explaining that past actions are unaffected. It also discloses the required authentication scope, adding value beyond the annotations. No contradiction is present.

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

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

The description is two concise sentences. The first states the core purpose, the second adds crucial clarification about side effects and requirements. It is front-loaded with the action and includes no extraneous 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 simple one-parameter delete operation, the description covers the effect, what is not affected, and the required scope. It omits error handling or idempotency details, but these are minor for this simple tool and are not essential for correct invocation.

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

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

Schema description coverage is 100%, with monitor_id fully described as 'The monitor's id, from create_monitor or list_monitors.' The description adds no additional parameter-level detail, so the baseline of 3 is appropriate since the schema already covers 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 clearly states the action: 'Delete one of your standing watches, so it stops firing.' This is a specific verb and resource, and it distinguishes from siblings like create_monitor and list_monitors. It immediately conveys what the tool does without ambiguity.

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

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

The description implies when to use it: when you want to stop a standing watch. It also adds a prerequisite ('Requires authentication and the monitors:write scope') which guides usage. However, it does not explicitly mention alternatives or when not to use it, but given the context of create/list monitors, the intent 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 goes well beyond them: unrecoverable with no undo, the definition is not retained, and deleting a shared view removes it for the team. It also discloses the authentication and tickets:write scope requirement, which annotations do not cover.

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 irreversibility warning and then the alternative routing. Every sentence carries distinct information: consequence, alternative, blast radius, auth requirement.

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, no-output mutation tool, the description covers the safety profile, the alternative, the sharing side effect, and the auth/scope needs. Nothing an agent needs to call this 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 view_id (sourced from list_saved_views) and expected_revision are already documented in the schema. The description adds no further meaning about parameter format or the revision-conflict reconciliation semantics, so the baseline 3 applies.

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

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

States a specific verb (permanently delete) and resource (saved views), plus an ownership constraint (YOUR OWN). It explicitly names the closest sibling, archive_saved_view, and contrasts reversible vs. permanent, so an agent can distinguish it without reading 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?

Gives explicit when-not guidance ('archive_saved_view is the reversible retirement and is almost always what is wanted instead; use this only for a view that should actually be gone'), naming both the alternative and the condition that selects it. Nothing 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?

The description states 'This removes the saved definition,' which is a destructive operation on the template. Yet annotations declare destructiveHint: false. That is a direct contradiction. Additionally, the description contradicts the semantic meaning of destructiveHint even though it adds useful detail about runs being unaffected and the workflows:write requirement. Because the description contradicts an annotation, this dimension scores 1.

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

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

Three sentences, each with a distinct purpose: the operation and ownership, the built-in caveat, and the side effect plus auth requirement. There is no filler, and all claims are front-loaded in the first sentence.

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 delete operation with no output schema, the description covers the key facts: who can delete, what is not deletable, the consequence of deletion, and the necessary scope. It does not state that deletion is permanent or irreversible, which is especially relevant because annotations do not disclose this. Aside from that gap, the context is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no extra meaning about the parameters, which is acceptable because the schema does the heavy lifting. There is no sign the description improves understanding of slug or expected_template_fingerprint, 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?

The description opens with a specific verb plus resource and adds two key qualifiers: 'the caller owns' and 'custom' as opposed to built-in templates. This clearly differentiates the tool from siblings like create_workflow_template and update_workflow_template. The agent immediately understands both what the tool does and what it does not.

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