ComputeFirst

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds two genuinely useful traits beyond that: a cursor-based pagination contract ('next' echoed back as 'before') and a degraded unauthenticated response shape ('signed_in:false'). The phrasing is terse and the auth condition ('a key') is never defined.

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 what the tool returns and followed by the paging mechanic. It is appropriately sized, though the trailing 'Without a key: signed_in:false' reads as a fragment that is hard to parse without surrounding context.

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

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

There is no output schema, so the description carries the burden of describing returns; it references a 'next' field and a 'signed_in' flag that exist nowhere else in the structured data. For a simple annotated read tool this is borderline adequate, but it leaves the response shape and what counts as 'a key' 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 coverage is 0% and neither parameter is described in the schema, so the description must carry the load. It successfully explains 'before' as the cursor from a prior response's 'next', but 'limit' (1-50) is never addressed, leaving half the parameters undocumented anywhere.

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 concrete resource and content: 'The account's recent calls and outcomes', which tells an agent this is an activity/history read rather than a config or search tool. It does not, however, differentiate itself from siblings such as 'profile', 'savings', or 'search', leaving overlap ambiguous.

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 an actionable rule for paging ('pass next as before for older ones') and implies an unauthenticated path ('Without a key: signed_in:false'), but never states when to prefer this tool over 'profile', 'savings', or 'search'. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds that it returns the input schema, limits, and examples, which is behavioral context beyond the hints. It doesn't mention auth or rate limits, but for a safe read that is minor.

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

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

One efficient sentence front-loads the return content and the lookup key. No waste, though it is terse enough to omit potentially useful qualifiers about id format or version defaults.

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?

Output schema exists, so return structure need not be explained, and the description correctly summarizes what it returns. However, with 0% schema coverage and no usage guidance, it should say more about how the id/version pair is consumed or when this tool is the right one among many catalog 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%, so the description must carry parameter meaning. It states the tool is identified 'by id and version', naming both required parameters, but gives no format, pattern, or version-semantics detail beyond the schema's own constraints. Marginal addition; baseline for two params with low coverage would be higher, but the description only names them.

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 (describe) and resource (one ComputeFirst catalog tool), and the title reinforces it. But it doesn't distinguish from sibling tools like search or activity, which might also surface tool info, leaving the agent to infer separation.

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 when-not-to-use guidance. It doesn't say to use this before execute to inspect a tool, nor differentiate from search or list_saved_tools, so an agent has no routing cue.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds real value by disclosing the return shape (deterministic result plus an unmeasured savings receipt), but the advertised 'Limits' are only a bare URL rather than an actual disclosure of rate or size constraints.

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

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

Three tight sentences with the action front-loaded, followed by return behavior and a limits pointer. No filler, though the trailing URL sentence conveys little on its own.

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 fully spelled out, and annotations carry the safety profile. However, for a generic dispatcher with a free-form nested 'input' object, the description omits error behavior, validation expectations, and the actual limits it points to, leaving meaningful 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 25% (just the optional 'model'), so id, version and input are undocumented in the schema. The description partially compensates by clarifying that id/version identify the catalog tool and input is that tool's JSON payload, but it says nothing about format, validation, or what a missing/unknown id does.

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: 'Run one ComputeFirst catalog tool by id and version with its JSON input.' The word 'one' implicitly contrasts with the sibling execute_batch, so an agent can reasonably separate the two, though the sibling is never named outright.

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 by the word 'one' (i.e., use execute_batch for several) rather than stated. There is no guidance on when to call describe/search/list_saved_tools first, or on prerequisites for having a valid id/version pair.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for disclosing behavior beyond them: dependent steps are skipped after a failure, nothing is retried automatically, each success counts as one execution, and per-input/result/response limits are 256 KiB. The work-budget and batch_work_limit skipping behavior is genuinely useful context. Minor deduction for restating the no-retry policy twice.

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

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

It is front-loaded with the core contract, but it is a dense run-on block of five-plus sentences with duplicated content ('nothing is retried automatically' vs. 'successful items are never retried automatically') and undefined terms like 'refused work' that the agent cannot act on precisely.

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 batch executor with an output schema present, the description covers the essentials an agent needs: cardinality, dependency/failure semantics, size limits, and budget behavior. It does not describe partial-failure result shape or permission/consent requirements for the wrapped tools, but the output schema partly covers the return contract.

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% and the nested operation properties (bindings.from, bindings.path, include_result) are already documented in the schema, so the description largely restates binding/JSON-Pointer semantics rather than adding syntax or constraints. The `batch_work_limit` reference adds meaning not present in the schema, but `model` gets no elaboration. 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 (Run), resource (ComputeFirst catalog tools), and explicit cardinality bound (1–20 in one request), which immediately distinguishes it from a single-call executor. It does not, however, name the sibling `execute` tool or state the condition that would route an agent to it, so differentiation is implicit 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?

Usage is implied by the batch/dependency framing (bindings from earlier results, include_result to omit intermediates), and there are edge-case directives such as 'Send additional factory operations separately' and 'Split refused work.' But there is no explicit statement of when to choose this over `execute`, nor prerequisites for calling it, leaving the agent to infer 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 already declare readOnlyHint=false and idempotentHint=true, and the description earns its keep by explaining the mechanism behind idempotency ('a stable request_id makes retries safe') and adding a data-handling constraint ('Leave out secrets and raw data'). It does not say where the feedback goes or whether it is reviewed, so it is helpful 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?

Three short clauses, each front-loaded and non-redundant: purpose, the sibling routing rule, the idempotency requirement, and the privacy warning. No sentence could be deleted without losing information.

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

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

For a write tool with no output schema and zero schema description coverage, the essentials (purpose, idempotency, privacy) are covered, but execution_ref is unexplained and the enum semantics of category are only implied. An agent could call it correctly enough, but not confidently for every parameter.

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 only partially does: it explains request_id's role in safe retries and hints at the category space via 'what helped or went wrong'. The execution_ref parameter and the specific category enum values are never mentioned, leaving a real gap for a 4-parameter 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 concrete action ('Tell ComputeFirst what helped or went wrong') that maps cleanly to sending feedback, and it explicitly routes one adjacent case ('a missing tool fits request_tool') to the correct sibling. The verb is informal rather than a crisp 'submit feedback', so it is clear but not maximally precise.

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 an explicit routing rule: missing-capability reports belong to request_tool instead of feedback, which is the single most likely sibling confusion in a 15-tool set. It stops short of stating when the other categories (wrong_result, hard_to_use) should be used, so it is clear context without full coverage.

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 context: the unauthenticated case returns signed_in:false with an empty library. It stops short of describing pagination or result-size behavior.

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 with zero filler, and the resource statement is front-loaded before the edge-case behavior. Nothing could be removed without losing meaning.

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

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

With no output schema, the description carries the return-shape burden and does name the fields and the empty/unauthenticated case. For a zero-parameter read tool this is nearly complete, lacking only ordering or paging 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The parenthetical field list is return-shape information rather than parameter semantics.

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

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

The description states the resource ('Tools saved in the account's library') and enumerates the returned fields (id, version, note), which is enough to separate it from siblings like save_tool, remove_saved_tool, and search. It never explicitly names an alternative tool, so it falls short of full sibling differentiation.

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

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

There is no when-to-use guidance and no routing to or away from siblings such as search or describe. The only conditional statement ('Without a key: signed_in:false and no tools') describes behavior, not when to select this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the signed-out return shape ('signed_in:false and the optional extras'). It does not explain what 'keys' or 'privileges' contain or how tool-request status is represented, which keeps it below 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 filler. The primary purpose is front-loaded and the edge case (no key) follows immediately, so 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?

There is no output schema, so the description carries the return-value burden and does so at a high level (keys, privileges, tool-request status, signed_in flag). It omits the concrete shape of the 'optional extras' and the privileges structure, which is the only meaningful gap for a zero-param read tool whose annotations already cover safety.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly conveys that no input is required and that output varies by key presence.

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 the resource and enumerates its contents: 'The signed-in account: keys, privileges and tool-request status.' An agent immediately knows this is a read-only identity/credential inspection tool, distinguishable from siblings like sign_in or request_tool. It falls short of 5 only because it uses a noun phrase rather than an explicit verb, though for a zero-param read tool that is a minor issue.

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 tool clearly answers 'who am I and what is my access state', and the 'without a key' clause hints at the signed-out case. However, no alternatives are named (e.g., sign_in to obtain a key, request_tool to change privileges), and there is no explicit when-to-use guidance. Adequate but leaves routing 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description's only extra claim, 'Without a key nothing changes,' is opaque — no 'key' parameter exists in the schema — and it adds no usable behavioral context beyond the annotations.

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

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

Very short and front-loads the core action, which is good. However, the trailing sentence about a 'key' is confusing rather than economical and does not earn its place given no key parameter exists.

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 mutation with no output schema, the description should clarify what happens on success, whether the removal is permanent, and what permission/'key' is actually required. Instead it leaves the one behavioral claim it makes unexplained and under-specifies the two required 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% and both parameters (id, version) are required and undocumented. The description only loosely maps them ('tool id and version') without stating format, allowed characters, or what distinguishes the version argument — minimal compensation for a full 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+resource: removing a tool id and version from the account's library. This implicitly contrasts with the save_tool/list_saved_tools siblings, though it never names them 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?

No guidance on when to use this versus save_tool, list_saved_tools, or execute. There is no mention of prerequisites (e.g., that the tool must already be saved) or of any alternative path.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write nature is already structured. The description adds genuinely new behavior: it explains the return value ('dollar value at public list prices; unknown stays null'), which matters because there is no output schema. It does not say whether submissions can be overwritten or re-sent.

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 dense sentences with the required parameter and the simple mode front-loaded, then the measured-comparison variant. Nothing is repeated from structured fields, though the telegraphic style ('Optional, for the person') 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 9-parameter write tool with nested objects and no output schema, the description covers most of the calling contract and explains the return, which is good. It still leaves 'provider' unexplained and the nested baseline/actual sub-fields undefined, so an agent could not populate every field confidently.

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 has to compensate. It does name model, estimated_tokens_saved, task_id, baseline_id, baseline, actual, whole_task:true and execution_ref, and groups them into two coherent modes. But it omits 'provider' entirely and gives no shape for the nested input/cached_input/output objects, leaving real gaps.

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: report your model id plus an estimate of tokens saved, and get back a dollar value. That is a clear action an agent can distinguish from a read-only listing. It never names the sibling 'savings' tool, so the boundary between reporting and reading savings data is left implicit.

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?

'Optional, for the person' signals this is a voluntary submission, and the second sentence implicitly defines two modes (simple estimate vs. measured comparison). However, it never states when an agent should prefer this over the sibling 'savings' tool, nor what prerequisites or consequences submitting has.

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 reveal the write/non-idempotent profile (readOnlyHint=false, idempotentHint=false), so the description earns credit for adding constraints outside structured data: the privacy rule 'Leave out secrets' and the consent coupling — contact_email is only supplied together with email_consent:true and only for a single ship notification. It still omits what happens after submission and duplicate-request behavior, which matters for a non-idempotent call.

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

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

Two sentences, front-loaded with the core purpose and then the parameter guidance; the terse 'Leave out secrets' clause manages to earn its place as a safety rule. No filler or restatement of the title.

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

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

For a submission tool with no output schema and only safety-oriented annotations, the description covers the request shape and the email consent path but is silent on what the caller gets back, how long review takes, and whether repeated submissions duplicate — gaps an agent would want before invoking.

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 meaning, and it largely does: 'the task' maps to description, 'optionally example input and output' maps to the two example fields, and it explains the contact_email/email_consent relationship — a cross-field constraint absent from the schema. It does not mention length caps or that description is required.

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 object — ask for a tool that does not yet exist — and scopes it with 'that does not exist yet', which cleanly separates it from siblings like search, execute, and save_tool that operate on existing tools. An agent can identify the intent 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 conditional 'a tool that does not exist yet' implies the agent should only call this after determining no existing tool fits, but no sibling is named as the prior step (e.g., search first, save_tool for existing ones). Guidance is implied rather than explicit, and no when-not-to-use cases are given beyond the existence qualifier.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them by clarifying that re-saving replaces the note, but the cryptic 'without a key nothing is saved' clause is unexplained and borders on noise rather than 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?

It is a single front-loaded sentence with little waste, and the note-replacement caveat is correctly parenthesized. The trailing 'Without a key nothing is saved' clause is ambiguous and undercuts the otherwise tight 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?

For a 3-parameter mutation tool with no output schema, the description covers the core write and the note-replacement behavior, which is adequate. It omits what happens to a previously saved different version, error behavior, and any clear authentication requirement beyond the vague 'key' reference.

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 does name all three inputs and correctly marks the note as optional, matching the required list. However it adds no format or constraint detail (the id pattern, the 100/200 character limits) beyond what the schema's type declarations already imply.

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 tool id and version to the account's library'), which lets an agent distinguish it from siblings like list_saved_tools and remove_saved_tool. It lacks any explicit sibling differentiation, but the action and target are 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?

There is no guidance on when to use this versus alternatives such as request_tool or list_saved_tools, nor any stated prerequisites. The trailing phrase 'Without a key nothing is saved' gestures at a precondition but never explains it, leaving usage context 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds real behavioral context beyond that: results depend on whether a key is supplied (account measured/estimated totals vs community verified totals), and it warns that 'Unmeasured is not zero', preventing a misinterpretation of the data.

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 sentence that is front-loaded with the core resource and keeps the most decision-relevant caveat ('Unmeasured is not zero') at the end. It is efficient, though the ambiguous 'with a key' clause 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?

With no output schema, the description usefully characterizes the return content (measured, estimated, or community verified totals) and flags the unmeasured-value pitfall. What remains thin is the meaning of the single input parameter and how authentication changes behavior.

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 param, and it only partly does -- it conveys that 'model' scopes results to a single model but never states the expected format or identifier semantics. The 'with a key' phrasing further muddles whether the parameter or credentials control the mode.

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 the resource (savings totals) and the scoping option (one model), so the agent knows it retrieves savings figures. However, the clause 'with a key' is cryptic -- it never says whether 'key' means the model parameter or authentication -- and it does not distinguish this tool from the sibling report_savings.

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 the model parameter is optional ('optionally for one model') but gives no guidance on when to call this versus report_savings or the other siblings. There are no stated prerequisites or exclusions, so the agent must 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?

Annotations already declare the safe read profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower; the description still adds real behavior beyond them — cap of 5 results, 3 by default, id/version/score fields, and that only a confident top match carries the input contract.

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

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

Three tight sentences: what it searches, what comes back, and what to do on a miss. Return details are front-loaded and nothing is padding.

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

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

An output schema exists, so return values need not be spelled out, yet the description still sketches the shape. Combined with annotations covering the safety profile, an agent has everything needed to call it correctly and interpret a miss.

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 conveys the query is a free-form English task, that limit tops out at 5 with a default of 3, and that include_contract governs whether the first match's input contract is returned. Upper bound and the 256-char limit of query are left to the schema.

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

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

States a specific verb and resource ('Search the ComputeFirst catalog'), the input form (an English task), and the result cardinality. An agent can distinguish it from list_saved_tools or describe without opening any schema.

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

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

Gives clear context (natural-language task) and an explicit fallback for the no-match case: 'request_tool can ask for one.' It does not contrast with siblings like list_saved_tools, which catalog saved tools, so the routing guidance is clear but not exhaustive.

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

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

Annotations only cover the generic mutation profile (readOnly=false, idempotent=false, destructive=false), and the description adds substantial behavioral context beyond that: the email is created unverified, the agent key is returned only once, the person must store it in client settings, and the agent must not repeat the key in conversation. These are non-obvious, high-stakes operating 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?

Everything is packed into a single dense sentence with the gating condition front-loaded, which is appropriate given the title marks the tool optional. It is slightly run-on, but nearly every clause (consent gating, one-time key, storage instruction, newsletter condition) carries necessary information.

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

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

With no output schema, the description explains what is returned (an agent key, once) and what the caller must do with it, covering the consent gate, the side effect of account creation, and the downstream benefits. An agent has enough to invoke this 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%, so the description carries the burden and does much of it: it explains that consent must be the explicit-when condition, and that newsletter should only be set on request. Email semantics (unverified, client-side storage) are also implied, though format/length constraints are left to the schema.

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

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

The description states a concrete action and resource: it creates a free account for the person's email and returns an agent key. The tool name 'sign_in' is slightly misleading since the actual behavior is account creation, but the description corrects this immediately and names the concrete benefits (saved tools, history, personal savings, higher limit) that distinguish it from siblings like list_saved_tools or savings.

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 an explicit precondition ('Only when the person explicitly asks for a free account (consent:true)') and a conditional for the optional flag ('newsletter:true only if they ask'). This tells the agent both when to call and when not to call, which is exactly the routing guidance needed.

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=false, idempotent=true, destructive=false and openWorld=false. The description adds real value beyond them: the consent guardrail and the fact that every resulting email carries an unsubscribe link, which tells the agent the consequence of the write is user-reversible. It stops short of describing error behaviour (e.g. duplicate emails) despite the idempotent 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?

Two short sentences, zero filler, with the consent constraint placed immediately after the action so the agent reads the guardrail before acting. Nothing is redundant with the title or schema.

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

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

For a simple two-parameter, non-destructive, idempotent tool with no output schema, the description covers the action, the consent precondition and the user-facing consequence. Only marginal gaps remain (duplicate handling, invalid-email behaviour), which the annotations partly mitigate.

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. It does clarify the meaning of 'consent' (the person asked, and it must be true), which the bare schema const does not explain, but it adds nothing about the 'email' parameter beyond 'an email'. Baseline 3 for a two-param tool with no schema prose.

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 pairs a specific verb ('Subscribe') with a specific resource ('an email to new-tool announcements'), so the action is unambiguous. It does not explicitly distinguish itself from any sibling (e.g. feedback or request_tool), but the function is distinct enough that routing confusion is unlikely.

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

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

'only when the person asks for them (consent:true)' is an explicit precondition that tells the agent when to call this tool and, by implication, when not to. No alternative tool is named, but there is no comparable sibling offering subscription, so this is sufficient context.

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