Pitch

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

Annotations already declare this is a non-idempotent, non-destructive write in a closed world, so the safety profile is covered. The description adds value beyond that by disclosing the visibility of the created entity ('private') and the boundary of what is persisted, though it says nothing about permissions or required preconditions.

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, action statement front-loaded before the boundary condition, with zero redundant or filler text.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a simple two-parameter creation tool the description is close to complete, with the only real gap being parameter-level detail.

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 adds no parameter information at all beyond the creation concept. With low coverage the description must compensate for the two undocumented fields (name, description), and it does not; the fields are only inferable from their names.

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

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

States a specific verb and resource ('Create a new private product') with the 'private' qualifier adding scope, and the second sentence explicitly distinguishes it from the record_* siblings. An agent can tell what this creates and what it does not 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 negative routing is explicit and maps to concrete siblings ('Does not save metrics, customer proof, or discount rules' → record_approved_metric/record_customer_proof/record_discount_rule). The positive trigger 'when the user asks' is vague, but the exclusions give solid 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 declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds behavior beyond annotations: results are a selection, unapproved facts are surfaced as such, and locked facts must not be contradicted. It does not describe pagination despite a limit parameter, which is a minor gap.

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

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

Front-loaded with the verb and purpose, then constraints and the sibling route. Several short guard sentences add policy value but edge toward redundancy; overall still efficient and each sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, with 0% schema description coverage, the description leaves productId and limit undocumented, which is a meaningful gap for an agent trying 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 0%, so the description must compensate. It defines only 'request' ('a brief topic query, never a chat transcript') and says nothing about productId or limit semantics, their formats, or the difference between the two required params. Two of three parameters remain undocumented.

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 ('Retrieve the approved sales record') and gives the operational goal ('before answering a buyer or drafting a reply'). It does not explicitly name how it differs from search_approved_facts in scope, but the 'Results are a selection' line and the sibling reference imply the distinction.

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

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

Explicitly names the alternative ('use search_approved_facts for a specific missing fact') and the condition that selects it. Also frames the timing of use ('before answering a buyer or drafting a reply'). No inference required.

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 'No changes are made' largely restates structured data. The one piece of added value is the ordering disclosure ('newest first'), which tells the agent how results are sequenced.

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

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

Two short sentences, front-loaded with the core action and ordering, with no filler. 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?

An output schema exists, so return values need not be described, and the description covers the core purpose adequately. However, with 0% parameter coverage and no usage routing, the definition is only minimally sufficient for a history-lookup 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 0% for two parameters (approvedFactId, offset), and the description fills neither gap. It vaguely implies a fact identifier but never explains the UUID format or what 'offset' paginates, so an agent gets no help beyond the bare schema.

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

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

The description states a specific verb and resource ('Read previous and new content for a saved approved fact') and adds an ordering guarantee ('newest first'). It is clearly a per-fact version-history read, distinguishable from revise_approved_fact and search_approved_facts, though it never names a sibling explicitly.

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

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

Usage is only implied: an agent can infer this is for inspecting the revision history of one already-approved fact, but there is no statement of when to prefer it over get_approved_context or search_approved_facts, and no exclusions or prerequisites.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds useful non-annotation context: results must be paged via offset, and returned IDs should be reused rather than guessed.

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, front-loaded sentences with no filler; the core instruction ('find the user's saved products') leads, followed by constraints.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description adequately covers usage, ID handling, and pagination, though it says nothing about result size or ordering.

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 only parameter is offset. The phrase 'Page with offset' explains the parameter's purpose (pagination) but adds no detail on bounds, defaults, or page size beyond what the schema's minimum/maximum/default already state.

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: find/list the user's saved products. It does not explicitly differentiate itself from siblings like create_product or search_approved_facts, but the 'saved products' scope is clear enough to identify the resource.

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

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

Gives concrete when-to-use context ('before answering or editing') and an explicit behavioral rule ('use the returned ID; do not guess products'). It stops short of naming an alternative tool or stating when not to use it, so it is not a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral rules: absent facts are treated as unapproved, missing discount approval is reported explicitly, and results are paginated evidence rather than a verdict. This goes meaningfully beyond the annotations.

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

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

Five short sentences, front-loaded with the core behavior and the evidence/not-approval distinction. Every sentence carries information, though the 'If a fact is absent...' and 'If no discount is approved...' lines are slightly repetitive in structure.

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?

An output schema exists, so return values need not be spelled out, and annotations cover the safety profile. The description fills in the domain rules an agent needs (absent = unapproved, offset paging for a complete audit), with the only real gap being undocumented parameter meaning.

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 three parameters, so the description carries the full burden. It hints at pagination semantics for 'offset' ('Page with offset') but says nothing about what productId scopes or what proposedText must contain, leaving two required parameters 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 concrete verb ('Show') and resource ('the locked approved record') and clarifies the tool audits proposed pitch text against approved facts. It also differentiates itself from write siblings by stating 'it does not save or approve anything,' though it never names a sibling explicitly.

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

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

Offers one real usage rule — 'Page with offset before claiming a complete audit' — which tells the agent how to use results completely. However, it gives no when-to-use versus get_approved_context or search_approved_facts, and no explicit exclusions beyond the generic 'does not save or approve.'

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 idempotent=true and destructive=true, and the description reinforces idempotency ("Identical retries leave history unchanged") while adding the immutability rule for LOCKED metrics and a do-not-invent guardrail. It adds real behavioral context beyond the annotations, though it does not spell out the full effect of destructiveHint (e.g., what a conflicting overwrite does).

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

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

Five sentences, each carrying a distinct constraint (approval, LOCKED meaning, locked-edit restriction, expectedRevision, idempotency, no-invention). Dense and front-loaded, with only minor redundancy in the two LOCKED-related sentences.

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

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

An output schema exists, so return format need not be described, and the description covers the key mutation constraints (approval gate, immutability, revision concurrency). It is nearly complete, though the enum's other values (DEVELOPING, UNKNOWN, RETIRED) and the roles of undeclared params remain unexplained.

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 full burden, and it only partially compensates: it explains the LOCKED enum value and the expectedRevision requirement for existing entries. It adds nothing for title, content, tags, revisionReason, or productId, leaving most parameters to be inferred from their names.

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 (save a number/metric) and front-loads the governing precondition that the owner must approve the exact wording. It explicitly distinguishes itself from revise_approved_fact by carving out locked metrics as out of scope for this tool.

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

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

Gives explicit when-to-use (only after owner approval), when-not (an existing locked metric cannot be changed here), and names the alternative (revise_approved_fact) for that case. It also flags the expectedRevision prerequisite for existing entries, leaving nothing to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, and the description meaningfully corroborates and extends these: 'Identical retries leave history unchanged' matches idempotency, while locking behavior ('an existing locked proof stays locked until the owner revises it') and the expectedRevision concurrency requirement add real context beyond the structured hints. It still says nothing about permissions/auth or what the recorded content does downstream, so not a 5.

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

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

Front-loads the critical approval precondition and is generally dense with no filler. However, three consecutive sentences restate the customerName rule ('pass only when approved', 'omit when not approved', 'do not invent a name'), which is mild 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?

The output schema exists, so return-value explanation is rightly omitted, and the description handles the policy-heavy semantics (approval, locking, revision). But with 8 parameters at 0% schema coverage and 6 undocumented, the definition is incomplete enough that an agent must guess at how title, content, status, and tags should be populated.

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 covers only 2 of 8 params (customerName and expectedRevision). The customerName guidance — pass vs omit and the consequence — is genuinely useful, but productId, title, status, content, tags, and revisionReason are left entirely unexplained in both the schema and the description.

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

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

The description names a specific action on a specific resource ('Save customer proof') and states its governing precondition (owner approval). It does not explain what a 'proof' record actually is — title/content/tags/status imply a knowledge-style entry — and never distinguishes itself from siblings like record_approved_metric or revise_approved_fact, 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?

Strong conditional guidance: pass customerName only when the owner recorded it, omit it otherwise, and use expectedRevision for existing entries. It sets clear when-to-use conditions but names no alternative tool (e.g., which sibling to use for revisions), so it lacks the explicit routing a 5 requires.

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

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

Beyond the annotations, it discloses two non-obvious behaviors: a locked rule stays locked until the owner revises it, and existing entries require expectedRevision (an optimistic-concurrency requirement). 'Identical retries leave history unchanged' restates idempotentHint=true rather than adding new information, but the locking and revision preconditions are genuinely additive given destructiveHint=true.

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

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

Five short sentences, each carrying a distinct rule, with the core action front-loaded ahead of the caveats. No filler, though the idempotency sentence slightly duplicates the annotation.

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?

An output schema exists, so return values need no explanation, and the description covers mode selection, locking, concurrency, and retry behavior. The main gap is the status enum's meaning, which matters for a tool whose required field is status.

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% across 8 parameters, so the description must carry the load. It clarifies decision (APPROVED/NONE) and adds the conditional requirement on expectedRevision, but says nothing about status (LOCKED/DEVELOPING/UNKNOWN/RETIRED), productId, title, tags, or revisionReason, leaving most of the surface undocumented.

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 ... discount or the rule that no discount is approved') and unpacks the two decision variants (APPROVED vs NONE), so an agent knows exactly what is being written. It does not name any sibling tool (e.g., revise_approved_fact) to differentiate, which keeps it 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?

It gives clear selection criteria for the two modes: decision APPROVED stores only owner-supplied terms, decision NONE records the absence of approval, plus the guardrail 'Do not invent a discount' and the precondition that existing entries require expectedRevision. No explicit when-not or named alternative is offered, so it is not 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?

With destructiveHint=true and idempotentHint=true already declared, the description still adds real behavioral detail beyond the annotations: LOCKED facts are revisable, omitting customerName actively clears the stored name, conflicting edits fail rather than overwriting, and identical retries leave history unchanged. The destructive side effect (name clearing) and the concurrency-conflict behavior are disclosed explicitly, which is exactly what the annotations cannot convey.

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

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

Five tight sentences, front-loaded with the scope and the kind constraint before the edge cases, and each sentence carries distinct information (LOCKED support, field preservation, name clearing, revision precondition, conflict/retry behavior). Slightly dense but 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?

An output schema exists and annotations cover the safety profile, so return values and the read/write nature need no restating. The description covers the hazardous and non-obvious behaviors well; the remaining gap is the undocumented status enum and revisionReason/tags semantics for a 9-parameter 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 0% across 9 parameters, so the description must carry the load; it explains expectedRevision (must come from retrieval), customerName (omit-to-clear semantics), and the title/kind preservation constraint. It leaves status, content, tags, revisionReason, and productId entirely unexplained, so compensation is only partial for a tool this wide.

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 (revise) and resource (an existing metric, customer proof, or discount rule) and enumerates the fact kinds that map to the record_* siblings, so an agent can tell this is the edit path rather than a creation path. It stops short of explicitly naming the alternative tools (record_approved_metric, get_fact_history), so sibling disambiguation is inferred 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?

It gives concrete operating conditions: preserve the existing title and kind, pass customerName only when the owner recorded it, and obtain expectedRevision from retrieval. That is clear when-to-use guidance, but there is no explicit when-not or named alternative for cases where revision is the wrong call.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds real value by disclosing that an empty query with offset browses all entries and that an empty result must NOT be treated as license to invent content. It doesn't mention result ordering or pagination limits beyond the offset param.

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, all front-loaded with the search/browse behavior first and the guardrail last; every sentence adds a distinct piece of information with no filler. Minor choppiness in "Do not fill it in." but it earns its place as a hallucination guard.

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?

An output schema exists, so return shape needn't be explained, and the description still clarifies the key edge case (empty result semantics). The one gap is the required productId parameter, whose role the agent must infer rather than read.

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. It explains the query param (literal title or content match, empty = browse all) and offset (browse every entry), but never explains productId, the only required parameter, leaving its scoping role to inference from the tool name.

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

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

States a specific verb (search/browse) and the resource domain (saved metrics, customer proof, discount rules), plus the literal title/content matching semantics. This clearly separates it from siblings like record_approved_metric, revise_approved_fact, and get_fact_history without needing to open any schema.

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

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

Gives explicit context ("Use this to verify a fact before revising it") and an important behavioral rule (an empty result means the fact is not approved, so don't fill it in). It does not name alternative siblings such as get_approved_context or get_fact_history for related lookups, so it stops short of full when-not/alternative routing.

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