Epovest

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

Adds context beyond annotations: all-or-nothing batch behavior, in-place update, series start timing, and error scenarios. 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?

Mostly concise and front-loaded, but slightly redundant with 'all-or-nothing' mentioned twice. Still efficient overall.

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

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

No output schema provided, and description only vaguely mentions returned keys ('keyword' or 'keywords') without specifying structure. Missing clear return value 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?

Schema coverage is 100% and description reinforces mutual exclusivity and all-or-nothing, but does not add significant new meaning beyond 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 clearly states the tool accepts discovered suggestions (domains) to become tracked keywords, distinguishing it from siblings like dismiss_keyword_discovery and list_keyword_discoveries.

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

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

Explicitly says to accept only when user says yes, and mentions error conditions (keyword_cap_reached, not_found). Does not explicitly contrast with dismiss tool but context implies it.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false, but the description adds substantial context: the check becomes REQUIRED, it is ticked via tick_surface_checklist, replaying restores from trash without duplicating, and there is a limit of 20 checks. The nuanced explanation of restates_canon (what makes a check perish with wording changes) goes well beyond annotations. No contradictions.

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?

Although the description is longer than average, it is densely packed and front-loaded with the primary purpose. Each subsequent sentence adds necessary detail (examples, idempotency, limits). The structure moves naturally from definition to usage to parameter nuance to operational behavior. 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?

Given the tool's complexity (4 params, nuanced idempotency, behavioral nuance) and the absence of an output schema, the description is remarkably complete. It covers what the check means, how it integrates with tick_surface_checklist, edge cases (restoration, no duplicates, maximum count), and the key parameter decision. No significant information 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%, but the description adds significant meaning beyond the schema. For restates_canon, it explains the key judgment call with a precise question and consequences. It also provides examples for label content and clarifies the default false behavior. This adds value beyond the property descriptions.

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

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

The description states a specific verb+resource: 'Add a check of your own to the checklist of one surface'. It clearly differentiates from sibling tools like update_surface_check, delete_surface_check, and tick_surface_checklist by focusing on adding a new custom check. The examples ('the pricing block quotes the canon boilerplate') further clarify what the tool accomplishes.

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 explicit when-to-use guidance: 'Reach for it whenever the person states something a page must carry that is theirs to decide'. It also gives concrete examples of such situations. However, it does not explicitly mention alternatives (e.g., update_surface_check) or when-not-to-use conditions, which would earn 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 indicate it is not read-only but is idempotent and not destructive. The description adds context that nothing is deleted, the line and history stay, and it describes the impact on source presence. This complements the annotations well.

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 front-loading the main action. It could be slightly more structured (e.g., bullets) but is efficient and clear.

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 simple action (toggling archived status), the description covers behavior, cautions, and effect on counting. No output schema exists, but the result is implicit. It is 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?

The schema covers both parameters with descriptions. The description reinforces the meaning of archived (true takes down, false puts back, omitted takes down) and provides guidance for corroboration_id to use list_corroborations. This adds 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 clearly states the tool's purpose: recording that a page is no longer there or putting it back live. The title also explicitly says 'Take a corroboration down, or put it back live.' This distinguishes it from siblings like create_corroboration or delete_corroboration.

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 advises to only take down after re-reading the address and finding it gone, and explains the effect on presence counting. It does not explicitly contrast with alternatives like delete_corroboration, but the context and sibling list provide implicit contrast.

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?

Description aligns with annotations (destructiveHint=true, idempotentHint=true). Adds details: nothing deleted, trackers keep status, answer carries tracker_count. No contradictions.

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?

Paragraph is informative but slightly verbose. Each sentence adds value, but could be tightened. Front-loaded with the purpose and main effect.

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 no output schema, description explains side effects, idempotency, default project, and tracker_count in answer. Covers all necessary context for correct invocation.

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

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

Schema coverage is 100% with descriptions. Description adds value: explains default behavior for archived parameter, and that project_id is always UUID from list_projects. Enhances understanding beyond 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 clearly states the tool files a project away, moves it to the end of list_projects with archived true, and stops offering it when filing a tracker. It distinguishes from siblings by explicitly mentioning archive_tracker and non-cascading behavior.

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 when to use (project served its purpose) and when not (trackers continue measuring). Mentions the default project and alternatives like archive_tracker for cascading. Clear usage context.

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 extensively explains behavioral traits beyond annotations: it moves the tracker, pauses measurement, stops spending, keeps sheet and scores readable, and is idempotent for already archived trackers. Annotations hint at destructive and idempotent, but the description adds concrete 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 front-loaded with the core action and then elaborates efficiently. Every sentence earns its place, though it could be slightly streamlined without losing value.

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 2 parameters and no output schema, the description covers most aspects: purpose, effects, idempotency, and persistence. It lacks mention of potential errors or return values, but these are not critical for a state-changing tool with annotations.

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 100% schema coverage, the schema already documents both parameters. The description reiterates the parameter meanings but does not add new information beyond what the schema provides, so it scores at baseline.

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

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

The description clearly states that the tool archives a finished tracker, detailing the specific effects like moving to the end of the list, pausing measurement, and stopping spending. It distinguishes from siblings by focusing on trackers, and the title 'File a tracker away' aligns well.

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 explicit context for when to archive (finished campaign, sold brand, ended trial) and mentions reverting with archived false and start_tracker. However, it does not explicitly compare with sibling tools like archive_project or provide when-not-to-use 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?

Discloses idempotency, effect on dismissed quests, state changes (sets state and closing date), and lifecycle (readable in closed history, reopenable). 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?

Single efficient paragraph with front-loaded main action. Every sentence adds value; no wasted words.

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

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

Given the tool's simplicity (1 param, no output schema), the description covers all relevant behavioral aspects including idempotency, edge cases, and lifecycle.

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 provides full description for quest_id, and tool description does not add extra information beyond that. 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?

Clearly states the verb 'mark a quest done' and resource 'quest'. Distinguishes from siblings by mentioning reopen_quest and implicitly differentiating from dismiss_quest.

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: use when the move happened. Mentions idempotency and safe retry. Also covers edge case of dismissed quests. Lacks explicit 'when not to use' but still strong.

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 context beyond annotations: it explains that the message lands in support threads visible to members and that a human will answer. Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature, but the description clarifies the human response process and thread 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?

The description is concise with two sentences that cover purpose, usage, and reply behavior. Information is front-loaded and every sentence adds value without 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?

Considering the tool's complexity (4 parameters, no output schema, basic annotations), the description is quite complete. It explains the workflow, when to use, and how to reply. Minor omissions like error handling or default behavior for missing thread_id are acceptable.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds extra value by explaining the purpose of thread_id (reply to an ongoing thread) and that subject is derived from message when omitted, which goes beyond the schema's brief descriptions.

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

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

The description explicitly states the tool's purpose: sending a message to the Epovest support team for reporting problems, suggesting improvements, or asking questions. It clearly identifies the verb ('send a message') and the resource ('humans behind Epovest'), and distinguishes it from siblings like get_support_thread by explaining the 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?

The description provides clear guidance on when to use this tool, such as when a tool refuses to work, when the product is missing something, or when the user asks to tell something. It also explains how to reply to an ongoing thread using thread_id and refers to get_support_thread for reading answers, though it doesn't explicitly state when not to use it.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds details beyond annotations: nothing is retyped, url/label/notes travel, publication date copied to notes, type derived from address, corroboration taken down but sheet intact, and replaying finds same line (confirms idempotency). No contradictions.

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 fairly concise and well-structured, starting with the core action, then scenarios, data handling, idempotency, and usage guidance. It could be slightly more streamlined but effectively conveys all 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?

Given no output schema, the description covers the process, data movement, and idempotency well. However, it does not specify the return value or result format. Without output schema, a bit more detail on what the tool returns would improve 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% and the description does not add new information about the parameter itself beyond what is in the schema. The description explains what happens to the data but not about the parameter format or constraints.

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 ('Move the page to the surface registry'), specifies the resource (corroboration), and distinguishes from the sibling tool 'convert_surface_to_corroboration' by mentioning the reverse move exists. It also gives scenarios (customer profile, listing on wrong side, source becoming reliable channel).

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

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

Explicitly states when to use ('customer has, or takes, the final say') and advises 'confirm with the user first'. It also mentions the reverse move exists, implying when not to use it. The description provides clear context on the scenarios.

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 beyond annotations by detailing the move's implications: URL, label, and notes travel; publication date remains unknown; the surface goes to trash with an alignment journal; the operation is reversible and idempotent. This rich context aligns with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and adds actionable 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?

Every sentence in the description serves a purpose: conveying the operation, side effects, reversibility, exceptions, and user guidance. The information is front-loaded with the core action, and the structure is logical and efficient.

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 simple input (one UUID, no output schema), the description covers the tool's behavior thoroughly: preconditions (confirm with user), side effects (trash, journal), reversibility, and a specific exception (own_domain). It is slightly lacking in explicit error handling or state machine details, but for this complexity it is ample.

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 does not add significant semantics beyond the input schema for the single parameter (surface_id). The schema already describes it as a UUID from list_surfaces. The description only repeats this context, so it meets the baseline for 100% coverage but provides no extra value.

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 explicitly states the action: 'Move a surface to the corroboration registry' and explains the effect clearly. It differentiates this tool from its reverse sibling (convert_corroboration_to_surface), making the purpose distinct.

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 guidance on when to use this tool: when a page should be moved to corroboration because someone else has the final say. It also specifies when not to use it (own_domain sites) and advises to confirm with the user first. The existence of the reverse move is noted.

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 annotations (all false), the description reveals key behaviors: URL-derived source and display name, instruction to only record read pages, confirmation requirement, and refusal types. This adds significant transparency 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?

The description is concise at 4 sentences, front-loaded with purpose, and includes guidance and refusals. However, it could be slightly more structured (e.g., bullet points for refusals) for even faster consumption.

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 6 parameters, no nested objects, and no output schema, the description covers purpose, usage guidance, parameter hints, and behavior. However, it does not describe the return value or confirmation feedback upon success, which could be useful 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 100%, so baseline is 3. But the tool description adds crucial context like 'URL-FIRST' and derivation rules for label, refusals, and warning against using home page. This adds meaning beyond the schema descriptions.

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

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

The description clearly states the tool records a page about a brand where someone else has final say, using specific verb 'Record' and resource 'page about the brand'. It distinguishes from sibling tools like create_surface by noting customer-controlled pages go elsewhere, and refusals are listed.

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

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

Explicitly says 'URL-FIRST' and that only the exact address is needed, with derivation of other fields. It tells when not to use: customer-controlled pages should use create_surface. It also states to only record pages actually read and confirm with user, and lists three refusals with their slugs.

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 the tool is idempotent on the triple (project, label, occurred_at), but the annotations set 'idempotentHint': false, creating a direct contradiction. This violates the scoring rule to score 1 when description contradicts 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 focused paragraph that efficiently conveys purpose, key nuance, idempotency, and side effects without unnecessary words. It is front-loaded with the primary action and progressively adds detail.

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

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

Given the tool has 5 parameters (3 required) and no output schema, the description covers core behaviors, parameter semantics, and side effects (annotation on citation curves). It lacks explicit return value info but adequately guides an agent for this creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema, such as explaining that occurred_at is the action date (not recording date), and how the label appears on citation curves. This provides meaningful extra guidance.

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 records an action in the logbook, specifying the verb 'Record' and the resource 'logbook entry'. It distinguishes from siblings like update_logbook_entry and delete_logbook_entry, and adds nuance about recording with a date.

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

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

The description explains when to use the tool (record an action) and clarifies the distinction between occurred_at and recording time. It mentions idempotency for safe retries but does not explicitly state when not to use it or mention alternatives like update.

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 discloses that no trackers are filed by this call ('Nothing is filed by this call') and that the canon is recorded as version 1. It also specifies the duplicate behavior: 'Refused with project_exists... reuse its id instead.' With annotations all false, the description carries the burden and handles it well.

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 dense paragraph but every sentence provides necessary context: purpose, canon rules, filing behavior, and duplicate handling. It's front-loaded with the main purpose and avoids 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 creation tool with no output schema, the description fully explains the key behaviors: what is created, what is not, how to use the returned id, and how duplicates are handled. The schema covers parameter details, so the description only needs to cover higher-level semantics, which it does thoroughly.

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 already describes all 13 parameters (100% coverage), but the description adds conceptual context by explaining the brand canon and the one-language rule. This clarifies the purpose of canon_* parameters and why canon_language settles language calls. It adds meaning beyond the schema's field-level descriptions.

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

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

The description opens with 'Create a project to file trackers under,' clearly stating the function. It distinguishes from sibling tools like create_tracker by explaining projects are containers for trackers and adds the per-brand scoping rule. The verb and resource 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?

It provides explicit usage rules: 'one project per BRAND, never per language' and instructs to pass the returned id as project_id when creating or updating a tracker. It also advises reusing an existing project via the project_exists error instead of duplicating. While it doesn't name sibling tools explicitly, the context makes the usage 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?

The description claims idempotent behavior on open quests ('calling again returns the quest already in the file'), contradicting the annotation idempotentHint: false. This is a direct contradiction, warranting score 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?

The description is concise, single paragraph, front-loaded with purpose and key behaviors (idempotency, closed quest handling). Every sentence adds value, 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?

The description covers main behavior (creation, idempotency, closed quest reopening) without output schema. It could mention error scenarios or return value, but is largely sufficient for a create operation with clear idempotency rules.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal value by explaining that 'title says the move' and 'notes carry context and links', but largely repeats schema descriptions. No significant new information.

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 adds a quest (a next move) to a project's file, with specific verb and resource. It distinguishes from sibling tools like complete_quest or update_quest by focusing on creation and idempotency behavior.

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 (adding a quest) and mentions idempotency for retries, but does not explicitly direct agent to alternatives like update_quest for modifications or list_quests for viewing.

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 explains that the surface is born 'never_aligned' and that alignment status derives from tick_surface_checklist verifications (not declared directly). It adds behavioral context beyond annotations (which only show readOnlyHint=false). However, it doesn't discuss failure modes, idempotency, or error handling.

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 packed with useful info but somewhat dense. It is front-loaded with the primary purpose, then explains URL-first and alignment. Could be slightly more concise, but every sentence serves a 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 6 parameters and no output schema, the description covers creation behavior, state ('never_aligned'), and dependencies (tick_surface_checklist). It doesn't describe return values, but for a creation tool this is acceptable. The parameter guidance is thorough.

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 description adds value by emphasizing that type and label are derived from URL and should be omitted on creation. This is critical semantic info beyond the schema. For other parameters, it adds little beyond the schema descriptions.

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

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

The description clearly states the tool registers a surface, defines what a surface is ('a page about the brand where the customer has the final say'), and distinguishes it from siblings like update_surface and delete_surface by focusing on creation. It uses specific verbs and resources.

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

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

The description gives explicit guidance: URL-first approach, omit type and label on creation (derive from URL), pass them only to correct derivation. It mentions the related tool tick_surface_checklist for subsequent steps. However, it lacks explicit 'when not to use' statements or direct comparisons to 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 are all false and provide no safety or side-effect hints, so the description carries the burden. It transparently discloses that the tracker measures nothing yet and only starts consuming credits upon start_tracker, which is a key cost-related behavior. It also exposes the default for next_survey_at, adding behavioral depth beyond 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?

Three sentences, front-loaded with the core purpose, then workflow and validation context. Every sentence adds distinct value with zero filler. Minor punctuation typo in the last sentence doesn't detract from the structural efficiency.

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

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

For a 12-parameter create tool with no output schema, the description covers the essential lifecycle (draft → launch), the billing model, and a key default timestamp. It doesn't describe the return value, but the draft/launch distinction is the most important contextual gap, and the schema already handles field-level details. Overall, sufficient for successful selection and 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% and each parameter already has detailed descriptions (e.g., project_id explains 'call list_projects', resolution explains HD counts). The description adds a modest extra for next_survey_at (default behavior at start) and notes shared validation rules, but this is a small increment over the schema's strong baseline, so a 3 is appropriate per calibration.

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

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

The description opens with a specific verb+resource 'Create a tracker' and immediately adds the crucial qualifier 'in draft', distinguishing it from sibling tools like start_tracker and update_tracker. It clearly answers what the tool does and differentiates it from related actions.

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 explicit next-step guidance: 'call start_tracker to launch it against the prepaid credit balance', which clarifies the intended workflow and when this create tool is the right choice vs its sibling launch tool. It also references validation parity with the app configurator, providing practical usage context, though it doesn't enumerate exclusions or alternative scenarios.

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 provide destructiveHint=true and idempotentHint=true. The description adds key context: the entry is soft-deleted ('waits in the trash') and can be restored with its annotation. It also clarifies that tool events remain unchanged, which is beyond what annotations convey.

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

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

The description is four sentences, each serving a purpose: action, usage constraint, soft-delete behavior, and side-effect clarification. It is front-loaded with the core action. Minor verbosity could be trimmed, but overall efficient.

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

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

For a single-parameter delete tool with no output schema, the description covers the essential behavioral aspects (soft delete, annotation removal, side effects on events). It does not specify return value or error handling, but the idempotentHint and destructiveHint provide safety. The description is sufficiently complete given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to obtain the entry_id ('call get_logbook to find it') and a constraint ('only manual entries carry an id'). This helps the agent correctly populate the parameter.

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

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

The description clearly states the action: 'Take a manual logbook entry out of the logbook, and the annotation it placed on the curves with it.' It names the resource (manual logbook entry) and distinguishes from siblings like create_logbook_entry and restore_logbook_entry.

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 explicitly says 'Only do it when the user asked for it: it is their logbook,' which guides appropriate use. It also mentions the alternative (restore_logbook_entry) and clarifies that tool events are unaffected, preventing misuse.

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 provide idempotentHint=true and destructiveHint=true. The description adds that the sheet and alignment journal are kept, and restore_surface brings them back, reinforcing idempotency and clarifying non-destructive aspects.

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 brief (three sentences), front-loaded with the main action, and every sentence is informative. No redundant or extraneous 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, idempotency, recovery, and side effects. Annotations complement but description adds necessary behavioral 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 100% and provides adequate description for surface_id (UUID format, call list_surfaces). The tool description does not add further parameter details, so baseline score of 3 applies.

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

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

The description clearly states the verb 'take out' and the resource 'surface', specifying that the page stops being followed and the registry stops asking to bring it in phase. It distinguishes from sibling tools like restore_surface, which brings the surface back.

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 explicit use cases: 'for a page that is gone (account closed, listing removed) or for a line that had no place there.' It also mentions idempotency and recovery via restore_surface, though it lacks explicit when-not-to-use 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?

Beyond the annotations (destructive, idempotent), the description discloses that nothing is truly lost—the check and cells are kept and readable with deleted=true, and restoration is possible. It also explains the side effects on the checklist (leaves list, stops holding page, stops accepting ticks), adding rich behavioral context without contradiction.

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 relatively compact and front-loaded with the core action, followed by usage context and a reassurance about reversibility. Each sentence adds value—no filler—though it is slightly longer than strictly necessary, it stays clear and purposeful.

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 (2 params, no output schema) and strong annotations, the description fully covers what happens, when to use, the soft-delete behavior, recovery path, and idempotence. Agents have enough to decide, invoke, and anticipate side effects without additional 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 description coverage is 100% for both parameters, so the schema already documents surface_id and check sufficiently. The description adds conceptual context by referencing 'check of your own' and pointing to list_surfaces/add_surface_check, but doesn't introduce new parameter syntax or format details beyond schema, hence baseline 3.

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

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

The description clearly states the action: 'Take a check of your own out of the checklist of a surface' and specifies behavioral outcomes (leaves list, stops holding page, stops accepting ticks). It distinguishes from siblings like add_surface_check and tick_surface_checklist, and even mentions restore_surface_check as the inverse, so it's 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?

Provides an explicit 'when to use' context: 'Use it when the requirement no longer applies to that page.' It also implies the alternative for reversal via 'restore_surface_check brings both back,' and notes idempotence ('Taking out an already taken out check answers the same'), fulfilling the when/alternative guidance criteria.

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 idempotentHint=true and destructiveHint=false, so the description's claim that 'Nothing is created or deleted' aligns. It adds the behavioral detail that the candidate will never be proposed again, which the annotations don't capture.

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 total. The first sentence states the purpose and effect, the second gives usage conditions, and the third provides alternatives. 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?

The description covers purpose, effect, when to use, and alternatives. For a tool with two parameters, no output schema, and sufficient annotations, this is fully complete.

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

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

The schema already provides descriptions for both parameters (100% coverage). The description adds valuable usage guidance: the URL must be 'exactly as list_corroboration_candidates gives it' and the project_id can be found via list_projects. This enhances the schema's 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 clearly states the action 'Refuse a suggested page' and specifies the effect 'it is never proposed again for this project'. This distinguishes it clearly from siblings like accept_keyword_discovery or create_corroboration.

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 explicitly states when to use the tool ('when the excerpt matched something else than the brand, or when the page is not worth recording') and contrasts it with the opposite move, directing to alternative tools (create_corroboration or create_surface).

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 annotations (idempotentHint, destructiveHint), the description adds important behavior: all-or-nothing on unknown domains, idempotent dismissal of already dismissed domains, and response format. This enriches the agent's understanding.

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 that front-loads the main purpose and covers all behavioral details without unnecessary words. Every sentence adds value.

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 no output schema, the description explains the return value (dismissed domain/list) and effect on suggestions. All key behaviors for a 3-parameter tool are covered, with minor room to add explicit alternatives.

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?

Input schema has 100% coverage; domain/domains/tracker_id are well-described. The description adds no new parameter-level meaning beyond what the schema provides, so baseline score 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?

The description clearly states the tool dismisses keyword discoveries (domains) in single or batch mode. It uses specific verb 'dismiss' and resource, distinguishing it from sibling tools like restore_keyword_discovery or list_keyword_discoveries.

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 effect of dismissal (never proposed again) and the all-or-nothing batch behavior, but does not explicitly state when to use this tool versus alternatives like accept_keyword_discovery. Usage context is implied rather than explicit.

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

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

The description adds value beyond annotations: explains idempotency (safe retry), side effects (state, closing date), and that the quest remains readable (non-destructive). No contradictions 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?

Three sentences efficiently convey purpose, idempotency, and result visibility without any fluff. Well-structured and front-loaded with the action.

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 mutation tool with one parameter and no output schema, the description fully covers behavior, effects, and relationship to reopen_quest. Complete and self-contained.

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 a clear parameter description. The tool description does not need to add more parameter semantics, 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 clearly states the tool sets a quest aside when the customer decides the move is off. It distinguishes from siblings like reopen_quest and complete_quest by specifying the action and effects.

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 usage context (when customer decides move is off) and mentions safe retry and reopen_quest for reversal. However, it does not explicitly contrast with other quest-related tools like complete_quest.

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

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

Annotations already declare readOnlyHint=true. Description adds that it returns every setting as it stands, reinforcing the read-only nature and the snapshot 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 sentences, front-loaded with purpose, no wasted words. Structure is clear and efficient.

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 no parameters and no output schema, the description fully covers what the tool does, what it returns, and how to use it (before update). 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?

No parameters; baseline is 4. Description adds no parameter details but that's irrelevant.

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

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

Clearly states the tool reads account settings and lists specific fields (legal name, billing country, etc.). Distinguishes from update_account_settings by name and usage context.

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 advises to read before update_account_settings and explains why: the answer provides current settings so only the intended field is changed.

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

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

Annotations already declare readOnlyHint=true, and the description adds rich behavioral detail beyond that: the exact structure of canon and history, that values are returned raw (perks is an ordered list, language is a short code), and the edge case where canon is not posted yet (history empty, canon_version null). No contradictions.

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 information-dense but every sentence earns its place: it explains the two main fields, the return structure, a concrete use case, raw value behavior, and an edge case. It is well-structured and not 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?

Given there is no output schema and the tool returns a complex object (canon, canon_version, history with nested changes), the description compensates fully by describing all components, the ordering, the before/after values, and the null case. It is sufficiently complete for an agent to understand what 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?

The only parameter project_id is fully documented in the schema ('UUID of the project: call list_projects to find it'), so schema coverage is 100%. The description does not add additional parameter semantics beyond what the schema already provides, meeting the baseline for full schema coverage.

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

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

The title and description clearly state this tool reads the canon of a project and its entire revision history. It uses the specific verb 'Read' and distinguishes itself from siblings like get_logbook and update_project_canon by explaining exactly what it returns (canon, canon_version, history) versus what others do.

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 an explicit use case: 'Reach for it to RE-PROPAGATE a revision', and explains how it relates to get_logbook. This tells the agent when to choose this tool over alternatives, including a specific scenario and what information it provides that others do not.

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 readOnlyHint annotation already declares this is a safe read operation, so the description doesn't need to repeat that. It adds value by explaining the meaning of derived fields (what monthly_estimate_minor represents, what suggested_topups contains, what min_topup_minor is), which is useful interpretive context. However, it doesn't describe the exact response shape for the reservations detail or pagination. With annotations covering the safety profile, a 3 is appropriate.

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 efficient and front-loaded with purpose, then flows into field semantics and edge-case handling. It's a single dense paragraph that earns each sentence — field derivations and the zero-consumption edge case are both relevant. Slightly long, but every part 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 0-param read tool, the description is thorough: it covers purpose, field semantics, suggested amounts derivation, minimum top-up floor, and the zero-consumption edge case with guidance on what to do. No output schema exists, so the description reasonably compensates by explaining the rich return payload. Minor gap: no statement about currency or formatting conventions, though those are inherent to amount_minor naming.

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?

There are zero parameters, and schema coverage is 100% (trivially, since there is nothing to document). The baseline for 0-param tools is 4. The description adds substantial semantic value by explaining what each returned field means and how they relate, compensating well beyond minimal expectations.

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

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

Clearly states it reads the prepaid credit balance: available credits, reserved amounts by surveys in progress, and per-reservation details. It explicitly names the read context (before starting a tracker, or when a call fails with insufficient_credits), distinguishing it from action-oriented siblings like topup_credits and start_tracker.

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

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

Explicitly states when to read it: before starting a tracker or when a call fails with insufficient_credits. It goes further by explaining when monthly_estimate_minor will be 0 and suggested_topups empty, and directs the agent to ask the person what they want to measure in that case. This is strong when-to-use guidance with clear context.

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=true, and the description adds detailed behavioral context: returning two lists (derived and free) with explanations of their sources. No contradictions.

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 somewhat lengthy but front-loaded with the core purpose. It includes necessary detail but could be more concise without losing 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?

Given the lack of an output schema, the description compensates by thoroughly explaining the return structure (two lists: derived and free) and their content. For a read tool with one parameter, it provides sufficient 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 description coverage is 100% and already documents the single parameter (project_id) with a clear description. The tool description does not add additional parameter semantics 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 clearly states it lists addresses of a brand that a watched page can link to, using specific verbs 'get' and 'list'. It distinguishes from its sibling tool 'set_link_targets' by focusing on reading rather than setting.

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 advises to 'Read it before setting anything', providing clear context for when to use this tool. It explains the purpose of derived vs. free lists but does not explicitly compare to other siblings like list_surfaces.

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 extensive behavioral details beyond the readOnlyHint annotation: item structure, source-specific fields, date semantics (occurred_at vs published_on), canon_version content, and the exact behavior of the deleted filter. This is far more than the annotations provide and greatly aids correct invocation.

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 covering many concepts. Every sentence adds useful information, from source composition to field meanings and conditional behaviors. While not as concise as possible, it is structured logically and avoids redundancy given the 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 must explain return value semantics, and it does so thoroughly: item types, field provenance, the meaning of occurred_at, published_on, and the deleted-only mode. It even references how to drive re-propagation. This makes the tool's behavior clear 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 coverage is 100% with each parameter described, so the baseline is 3. The description adds meaningful context, such as what counts as a 'tool' event and that tool events carry no category, reinforcing the source parameter's semantics. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool reads the logbook of a project, listing dated moves newest first. It distinguishes itself from sibling tools like create/update/delete_logbook_entry by focusing on the read operation. The verb is implicit but reinforced by the title and the phrase 'read the logbook'.

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 and how to filter via source, category, and deleted parameters. It explains the two sources and the use case of interpreting tracker curve movements. It doesn't explicitly name alternatives, but the distinctions are clear from the description.

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 readOnlyHint annotation, the description discloses behavior such as ordering ('newest surveys first'), pagination, and the presence of fields like cited sources, uncited_sources, and searched. It also warns that include_raw adds a 'heavy' full engine payload, which is important for performance expectations. No contradiction with annotations exists.

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

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

The description is three sentences, front-loaded with the core purpose, then details on response contents, and a practical warning about include_raw. Every sentence adds value with no redundancy or filler, making it efficiently structured.

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 9 parameters and no output schema, the description compensates by detailing what each answer carries, along with ordering and pagination behavior. It lacks explicit mention of the response envelope or error handling, but given the schema covers parameters and the description covers response semantics, it is sufficiently complete for an agent. It could be slightly richer on integration with sibling tools like get_results.

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?

All 9 parameters have descriptive schema entries, so the baseline is 3. The description adds extra meaning for include_raw by calling it 'heavy' and advising to ask for it only when needed, which enriches that parameter. Other parameters like q, tone, and survey are not further elaborated beyond their schema descriptions.

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

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

The description clearly states the tool returns 'raw answers of ONE AI engine for a tracker, newest surveys first, paginated', specifying the resource (tracker/engine), action (get), and scope. This distinguishes it from siblings like get_results and get_source by focusing on raw per-engine answers, and it outlines key response fields.

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 that this tool is for fetching raw answers from a single AI engine for a tracker. It doesn't explicitly name alternatives or exclusions, but the use case is evident. The only explicit guidance is the warning that include_raw is 'heavy' and should be used only when needed, which is a helpful prerequisite caveat.

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 readOnlyHint annotation already marks this as a safe read operation; the description adds useful behavioral details such as row composition, chronological order, and analyst-dependent fields. It does not contradict the annotations, though pagination or default behavior is not disclosed.

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

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

The description is two sentences long and packs the essential row structure, ordering, and field variation without unnecessary words. All sentences earn their place.

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

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

With no output schema, the description provides a solid mental model of the returned rows and their varying fields. It is not fully complete (e.g., no mention of filtering behavior or pagination), but is sufficient for a read-only series retrieval 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?

All three parameters have schema descriptions and enums, so the schema already covers parameter semantics. The description adds output context but not additional parameter-level detail, matching the baseline for high 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 identifies the tool as retrieving the score series of a tracker, with a specific row grain (per analyst, keyword, engine, tracker version, survey period) and chronological ordering. This distinguishes it from sibling tools like get_responses and list_trackers.

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 the tool is for retrieving historical score data but does not explicitly state when to use it over alternatives or provide exclusion criteria. Context is clear, yet there is no direct comparison to related 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 declare readOnlyHint=true, and description confirms read operation. Adds that it returns 'domain and its AI Authority on each AI', which is useful beyond annotations. No contradictions.

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 key information. Every sentence serves a purpose 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 simple read tool with one parameter and no output schema, description provides enough to understand what it returns and how to use it. Could be slightly more explicit about return structure, but adequate.

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 schema already describing source_id as UUID and referencing list_sources. Description merely echoes this, adding no new semantic depth.

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 clearly states the tool reads a single source by ID, returning domain and AI Authority. This distinguishes it from list_sources which lists/filters, so purpose is specific and unambiguous.

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

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

Explicitly advises to use list_sources to find a source ID, guiding the agent to the correct precursor. Does not explicitly cover when not to use, but context is 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?

Annotations declare readOnlyHint=true and openWorldHint=false. The description adds that it returns messages and answers, but does not disclose other behavioral aspects like pagination or error handling. It does not contradict annotations.

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

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

Two concise sentences with no redundancy. Front-loaded key information. Every word adds value.

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

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

No output schema exists, but the description hints at return content (messages and answers). Covers the essential behavioral context for a simple retrieval tool.

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

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

Schema coverage is 100% and the parameter description is adequate. The tool description adds no extra meaning to the single parameter beyond what the schema provides.

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

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

The description clearly states it retrieves one support thread with messages and answers. The title 'Read a support thread' reinforces the action. It distinguishes from siblings like list_support_threads (listing all) and contact_support (creating).

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 explicitly says to use it after contact_support to relay the answer. While it doesn't list when not to use, the context makes it 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 declare readOnlyHint=true, which the description aligns with (it discusses reads, never mutations). The description adds substantial behavioral context beyond annotations: page clamping behavior, on_demand semantics distinguishing manual vs cadence checks, listed status meaning, and the 'other' cost line that stays visible so nothing drops out of totals. It also reveals output nuance like months_total for completeness checks.

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 and information-rich but quite long (runs ~300 words) for a read-only tool. It packs a lot of valuable detail, so few sentences are wasted, but a shorter version could convey the three-answer structure and key caveats more accessibly. The content justifies its length, yet it risks overwhelming the agent.

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 no output schema and 50% schema coverage, the description carries a heavy burden and largely delivers: it enumerates the three response shapes, key fields (this_month_forecast, by_month, total_spent_minor, entries), cost-line breakdown, tracker_link reference (leading to get_results/get_responses), created_at timestamp semantics, and pagination. Missing: what 'minor units' conversion looks like and whether amounts need currency conversion, but the mention of wallet currency helps.

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% — the schema documents type, month, and their meaning, but page and per_page lack descriptions. The description compensates by explaining the month filter semantics (single YYYY-MM) and the type enum, and adds the crucial pagination behavior (page clamped, stop on page>=pages) that the schema omits. Some compensation beyond the baseline 3, but the description doesn't enumerate every parameter explicitly.

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 clear subject: 'What the account SPENDS' with three distinct answer shapes (monthly forecast, per-month actual, window total). It differentiates from siblings like get_credits (explicitly mentioned at the end) and get_account_settings. Purpose is clear and specific, though the verb 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?

The description explicitly instructs when to report each of the three answer shapes, warns against mixing them ('must never be mixed up'), differentiates forecast from real spend, and states when to use get_credits instead ('gives what is left to spend'). It also covers the single-month filter, the type filter, and flags that entries are paginated with a clamped page.

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 readOnlyHint=true and openWorldHint=false. The description adds beyond this by revealing the list is recomputed on every read from raw payloads, surveys_scanned indicates coverage, and already filed pages are excluded. 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 lengthy but each sentence adds value: explaining columns, behavior, and workflow. It is well-structured but could benefit from more concise formatting like bullets for the row fields.

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

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

Given the lack of output schema, the description fully explains the return format including all fields (excerpt, matched_by, suggested, page_check, checked_at) and their possible values. It also covers edge cases like 'no_page' and blocks. The tool's behavior and relation to other tools are thoroughly described.

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 a descriptive parameter description. The tool only has one parameter (project_id) and the description does not add extra semantics beyond what the schema provides, meeting the baseline for full coverage.

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

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

The description clearly states the tool lists pages where search engines showed the brand, and explicitly distinguishes itself from filing tools like create_corroboration. It provides specific verb-resource 'list pages' and explains the content, making it unique among siblings.

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

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

The description explicitly provides alternatives: 'to file one, call create_corroboration or create_surface; to refuse one, dismiss_corroboration_candidate.' It clarifies this tool is for viewing suggestions only, giving clear when-to-use and when-not-to-use context.

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 readOnlyHint annotation, the description adds ordering (live ones first, then archived true) and details on return fields (address, domain, publication date, notes). No contradictions 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 verbose and mixes core purpose with conceptual explanation about control and registry. While front-loaded, it could be more concise.

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 explains return fields and ordering, which is sufficient for a listing tool with one parameter. However, it omits details on pagination or limits, which are not critical but would improve 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?

Only one parameter (project_id) with 100% schema description coverage. The description does not add additional semantics beyond the schema's explanation, 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 clearly states the tool lists corroborations for a project ('pages about the brand where someone else has the FINAL SAY') and distinguishes from the sibling tool list_corroboration_candidates, which proposes pages already shown by search engines.

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 about the tool returning final declarations vs. candidates, but lacks explicit guidance on when to use this tool over alternatives or when not to use it.

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

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

Annotations only indicate readOnlyHint=true and openWorldHint=false. The description adds significant behavioral context: recomputed on every read, includes dismissed list, lists are disjoint, and a dismissed domain is never suggested. This exceeds annotation coverage.

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 somewhat long but front-loads the purpose efficiently. Every sentence adds value, though some redundancy exists. Could be slightly more concise.

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 one required parameter and no output schema, the description provides complete context: explains what the output contains (suggested and dismissed domains), their relationship, and how to use the results. No 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?

The schema coverage is 100% with one parameter (tracker_id) already described in schema. The tool description does not add meaning to the parameter beyond what the schema provides, but baseline 3 is appropriate given high 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 tool lists keyword suggestions discovered on a tracker. It distinguishes from sibling tools like accept_keyword_discovery and dismiss_keyword_discovery by explaining the concept of dismissed domains and that lists are disjoint.

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

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

The description explains when to use the tool: to relay suggestions to the user and that the decision to track is theirs. It implies when not to use by noting dismissed domains are never suggested, but doesn't explicitly contrast with other 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?

The description adds behavioral context beyond annotations: it specifies the sorting order (in use first, then archived) and that trackers without a project are under a virtual Default project. Annotations already indicate read-only and closed world.

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 wasted words. The first sentence explains the concept, the second adds ordering and default project details. Front-loaded with the main 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 no parameters and annotations present, the description fully explains what is listed, the fields, ordering, and the default project. No obvious gaps for a list tool.

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

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

No parameters exist, so the baseline is 4. The description adds meaning by detailing the returned fields (id, name, brand canon with version, archived flag, tracker count) and ordering, compensating for the lack of an output 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 clearly states it lists projects, explains what projects are (folders trackers are filed under), and specifies that they have no effect on measurement or billing. It distinguishes from siblings like create_project and archive_project by focusing on listing and organization.

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 guidance on when to use this tool versus alternatives. It is implied that it is used to retrieve a list of projects, but there is no mention of alternatives or when not to use it.

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

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

Annotations already indicate readOnlyHint=true. The description adds ordering (newest first), default status (open), and behavior for closed history. No contradictions.

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 verbose with multiple clauses and references to other tools. While front-loaded with the main purpose, the additional details on pending items make it longer than necessary.

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

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

No output schema exists, and the description only partially explains the response structure (e.g., ordering, pending items). Missing explicit return format or fields.

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% but the description adds context: for 'status' it explains the meaning of each enum value and the default; for 'project_id' it clarifies scope. This adds significant 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 clearly states it lists quests and distinguishes from siblings like list_corroboration_candidates and list_keyword_discoveries. The verb 'list' and resource 'quests' are specific.

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

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

The description explains when to use status=open vs done/dismissed and references related tools for further actions. However, it lacks explicit 'when not to use' or alternatives beyond the listed 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?

Despite the readOnlyHint and openWorldHint annotations, the description adds substantial behavioral detail: the 0-100 AI Authority scale semantics ('An engine with no value has not cited the domain lately, which is not a zero'), the account-scoped nature of the map, the registrable domain unit, and the stability of the scale across measurements. This goes well beyond what annotations provide.

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 long, dense paragraph (200+ words) that mixes conceptual background, scale explanation, and usage guidance. It is not front-loaded with a direct imperative or a clear 'list' statement, and it could be shortened by moving some details into schema descriptions or bullet points. Every sentence adds information, but the structure is not concise.

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 read-only list tool with no output schema, the description explains the shape of entries (domain + AI Authority per AI), the meaning of the scale, the unit (registrable domain), and the world boundary (account surveys). It does not explicitly state pagination or return field details, but the schema covers parameters, and the description provides the necessary conceptual model to interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add meaningful parameter semantics beyond what the schema already provides; for example, project_id's full behavior is already detailed in the schema. No credit is given for restating schema content.

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 defines the resource (the Atlas of sources) and the action (search/list), stating 'The Atlas: the sources the AIs cite when they answer YOUR trackers' and 'Use it to see where an answer comes from on a subject'. It distinguishes from siblings like get_source by focusing on the aggregate map, though it lacks an explicit contrast with get_source.

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 a clear use case: 'Use it to see where an answer comes from on a subject, and which places are worth existing on.' It also explains the scope (account surveys, project filtering) and the stable scale, giving context for when to use it. It does not explicitly mention alternatives or exclusions, but the contextual guidance is 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?

Annotations already indicate readOnlyHint=true. The description adds useful behavior: ordering (most recent first) and content (asked, answered). No contradictions. Lacks details on pagination or limits, but these may not exist.

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

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

Single sentence with clear purpose. The second sentence about sharing is somewhat redundant but not overly verbose.

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

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

No output schema, so description must explain return values. It mentions asked/answered but omits fields like thread ID, date, etc. Adequate but not fully comprehensive.

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?

No parameters in schema, schema coverage is 100%. Baseline score of 4 applies as description does not need to add parameter info.

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

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

Clearly states the tool lists support threads, ordered most recent first, and mentions the information included (asked, answered). However, it does not explicitly distinguish from sibling tool 'get_support_thread'.

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 tool versus alternatives like 'get_support_thread'. Lacks any context about prerequisites or 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?

Although annotations include readOnlyHint=true, the description adds extensive behavioral context: how statuses are derived from checklist cells, that setting aside the last canon cell is refused, domain_authority semantics ('an engine absent from engines has not cited the domain lately, which is not a zero'), and the behavior of the deleted parameter. 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 a single long paragraph, dense with domain concepts. While every sentence provides valuable context, it is not front-loaded and could be more structured. However, the complexity of the tool justifies the length, and there is no redundant 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?

The description thoroughly explains what each surface carries (type, url, label, languages, notes, checklist, status, domain_authority), the status derivation rules, the distinction from corroborations, and the meaning of domain_authority fields. With no output schema, this completeness is essential and well-covered.

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 meaningful context beyond the schema: sort 'orders and never filters' with off-map domains closing the list, deleted shows surfaces 'most recently taken out first' with deleted_at, and project_id points to list_projects. This elevates the parameter understanding.

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 'The surface registry of a project' and clearly states that this tool lists the surfaces of a project. It explicitly contrasts surfaces with corroborations and names the sibling tool 'list_corroborations', providing a specific verb+resource with 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?

It provides explicit usage guidance by distinguishing when to treat something as a surface versus a corroboration ('a page the customer can change is a surface, a page where someone else has the final say is a corroboration') and names the alternative tool. It also says 'Start here to find a surface id', indicating when to use 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?

Description adds behavioral context beyond annotations: ordering (followed first, then archived) and the archived flag with archived_at. Annotations already indicate readOnlyHint=true, so no contradiction.

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, perfectly front-loaded: first sentence states purpose and scope, second sentence adds usage guidance. No unnecessary 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 list tool with one optional parameter and no output schema, the description adequately explains ordering, returned fields, and filtering. No missing critical 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?

Input schema has one parameter with full description (100% coverage). Description adds value by explaining how to use the filter and what happens when omitted, surpassing the baseline.

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

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

Description clearly states 'List the trackers of the account' and specifies the returned fields: configuration, status, keywords, analysts, project, and cost per survey. It also indicates the primary use case: finding a tracker ID. This distinguishes it from sibling tools like list_projects.

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

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

Explicitly says 'Start here to find a tracker id' and describes filtering by project_id, including the 'default' option. However, it does not explicitly state when to use alternatives, though the purpose is 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?

The description adds that the score series is kept and that the action is reversible, which goes beyond annotations (idempotentHint=true, destructiveHint=false). It does not mention error conditions like pausing an already paused tracker.

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 with essential information front-loaded. No redundant words; each sentence adds value.

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 simplicity (one parameter, no output schema), the description adequately covers the core behavior and state transition. It does not describe error handling or side effects for invalid inputs, but this is acceptable for a straightforward 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?

Schema coverage is 100% with a clear description of tracker_id. The tool description does not add additional parameter-level meaning, so baseline 3 applies.

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

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

The description clearly states the verb 'pause' and the resource 'tracker,' specifying it pauses measurement of an active tracker. It distinguishes from siblings by noting that 'start_tracker resumes it.'

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

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

The description implies it should be used for active trackers and mentions resumption via start_tracker, providing good context. However, it does not explicitly state when not to use it or alternative tools.

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

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

Annotations already include idempotentHint=true, but the description adds valuable behavioral context: renaming preserves id, canon, trackers, surfaces, logbook; case/accents/spacing are normalized; sending the same name is a no-op. This goes beyond the structured annotations without 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?

The description is slightly longer than strictly necessary but every sentence contributes useful information. It is front-loaded with the core action and distinguishes from sibling tools without 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 rename tool with no output schema, the description covers what changes and what doesn't, uniqueness behavior, idempotency, archived projects, and how to handle naming conflicts. It comprehensively answers likely agent questions.

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% for both parameters, so baseline is 3. The description adds meaning by clarifying 'name' is the folder name (not the canon) and emphasizes uniqueness and case-insensitivity, providing extra semantic context 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 clearly states the tool renames a project (the folder name), differentiating it from updating the canon via update_project_canon. It explicitly says 'Use it for the name of the folder; the wording of the brand itself is the canon, and it moves with update_project_canon.'

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 when-to-use guidance: 'Use it for the name of the folder' and names the alternative for canon changes. It also explains uniqueness rules and the need to consult project_exists for name conflicts, and notes archived projects can be renamed.

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?

Description adds context beyond annotations: clears closing date, keeps history, safe retry. Annotations already state idempotentHint=true and destructiveHint=false, and description aligns without contradiction.

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: first explains core action, second clarifies idempotency and history preservation, third gives usage tip. No wasted words, front-loaded efficiently.

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

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

For a single-parameter, no-output-schema tool with good annotations, the description fully covers what the tool does, its effects, safety, and how to find the input. No gaps remain.

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 its description already explains the quest_id parameter. The description restates the UUID context and the lookup method, adding no new semantic detail beyond what the schema provides.

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

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

The description clearly states the action: 'Put a closed quest back in the file' and explains it returns among open moves with its history. It distinguishes from siblings like complete_quest or dismiss_quest.

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 advises to call list_quests with status done or dismissed to find the quest. Also notes that calling again is safe and leaves it open. Lacks alternatives or when-not-to-use but sufficient for the simple use case.

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 elaborates on the idempotentHint annotation by stating 'Idempotent and never refused' and clarifying what happens with a domain that wasn't dismissed. It also explains that the operation affects the tracker's dismissed list, adding transparency beyond 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 well-structured and packs significant information into three sentences. It could be slightly more concise, but it avoids redundancy and is front-loaded with the core 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 lack of an output schema, the description adequately covers input behavior, parameter constraints, and the nature of the response (restored domain or list). It provides enough context for an agent to use 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 description adds crucial context beyond the schema: the mutual exclusivity of domain and domains ('send this OR domains, never both'), and the all-or-nothing behavior for the batch parameter. These details are not present in the schema descriptions.

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

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

The description clearly states the tool's action: restoring one or more dismissed domains, making them eligible for discovery again. It explicitly identifies the tool as the counterpart of dismiss, providing a distinct verb-resource pairing.

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 specifies when to use the tool: 'for when the user changes their mind' about a dismissal. It also explains idempotent behavior and that restoring a non-dismissed domain simply leaves it eligible, guiding appropriate use.

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 idempotentHint and non-destructive annotations, the description adds that the entry is restored with its annotation on curves. This supplements the structured data with 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?

Two sentences, no fluff. The first sentence states the core purpose; the second provides usage guidance and explains idempotency. Every word 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?

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description fully covers what the agent needs: what it does, how to find the input, and what happens when the entry is already restored.

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

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

The single parameter entry_id is fully described in the input schema with a usage hint. The tool description does not add new information beyond what the schema already provides, so it meets the baseline for high 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 ('bring back'), the resource ('logbook entry'), and the key behavioral aspect ('with the annotation it placed on the curves'). It distinctly differentiates from sibling tools like delete_logbook_entry and create_logbook_entry.

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 instructs the user to call get_logbook with deleted='only' to find entries to restore, and notes that restoring an already-present entry is idempotent. Provides clear context for appropriate use, though does not explicitly state when not to use it.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description aligns by stating 'bring back...as they were' and that restoring an already-registered surface returns the same. The description adds value by specifying what gets restored (sheet and alignment journal), though it could mention permissions or 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 two sentences long with no extraneous information. It efficiently communicates the action, prerequisites, and idempotent behavior.

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 single parameter, good annotations, and no output schema, the description is fully adequate. It covers how to find the input, what the tool restores, and the idempotent outcome, leaving no gaps for the 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?

The input schema has 100% coverage with a single parameter that has a clear description ('call list_surfaces to find it'). The tool description reinforces this by mentioning the same lookup step, but does not add new semantic meaning beyond what the schema provides.

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

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

The title and description clearly state that the tool brings a surface back to the registry with its sheet and alignment journal. It distinguishes itself by specifying the restoration action and mentioning that restoring an already-registered surface returns the same, which avoids confusion with sibling tools like 'create_surface' or 'delete_surface'.

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 explicitly instructs to call 'list_surfaces' with 'deleted' set to 'only' to find surfaces to restore, providing a clear prerequisite and alternative path. It also notes the idempotent behavior of restoring an already-present surface, giving precise usage 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 indicate idempotentHint=true and readOnlyHint=false. The description adds valuable behavioral context: it becomes 'work again' and needs verification, and it explains the source of valid checks (list_surfaces with deleted true). It also reinforces idempotency by stating restoring an existing check 'answers the same.' No contradictions 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 three sentences, front-loaded with the core action and immediate consequence. Every sentence earns its place: the first states what it does and its effect, the second provides the source for valid checks, and the third handles an idempotency edge case. No unnecessary words or 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?

Given the tool's moderate complexity (2 params, no output schema, annotations for idempotency), the description covers the essential context: what is restored, how to find restorable checks, the consequence on verification, and an edge case. It does not mention error conditions or return values, but these are not critical for this simple restore operation.

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

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

Schema description coverage is 100% for both parameters (check and surface_id), so the baseline is 3. The description adds minimal extra meaning about parameters, only reinforcing that the check key comes from list_surfaces and restoring brings back cells. No significant parameter-level details 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 clearly states the action: 'Bring a check of your own back to the checklist of a surface' with the specific resource (surface checklist) and verb (restore). It distinguishes itself from sibling tools like add_surface_check (adds new) and delete_surface_check (removes) by focusing on restoration of previously deleted checks.

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 on when to use the tool: to restore checks that are marked 'deleted true' in list_surfaces. It also covers the edge case of restoring an already-existing check. It does not explicitly name alternative tools for adding or deleting checks, but the guidance is sufficient for selecting this tool over 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?

Discloses that the list replaces previous state, empty list keeps derived ones, and response returns full state. Adds context beyond annotations (idempotentHint, destructiveHint). No contradiction.

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?

Description is clear and front-loaded with purpose, though slightly verbose. Every sentence contributes value; could be slightly tighter.

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

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

No output schema, but description explains return value (derived addresses included). With rich annotations and schema, description is sufficient for correct invocation.

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

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

Schema coverage is 100%. Description adds context for project_id (sourced from list_projects) and clarifies link_targets is the full list that replaces. Baseline 3 with minor added value.

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 clearly specifies the tool sets 'free addresses of the brand' and explains what those are (satellite domains, tracking links, etc.), distinguishing it from sibling tools like get_link_targets.

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 advises calling get_link_targets first and confirming with user before replacing. Provides clear context but does not explicitly state when not to use.

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 behavioral context beyond the annotations: it discloses that the tool can be refused with insufficient_credits, that the error response contains a top_up_url to pass on, and that starting an already active tracker is a no-op (consistent with idempotentHint). It also implies a cost implication (prepaid credit consumption), which annotations do not convey.

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

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

The description is three concise sentences with no filler. The first sentence states the primary purpose, the second explains an important error case and the required follow-up action, and the third clarifies idempotency. Every sentence earns its place and the structure 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?

For a tool with a single parameter, rich annotations (readOnlyHint, idempotentHint, destructiveHint), and no output schema, the description is complete. It covers the operation, the failure mode, the fallback action, and the idempotency behavior, leaving no significant gaps for an agent to invoke 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 input schema has 100% coverage: tracker_id is described as a UUID and instructs to call list_trackers. The tool description does not add further meaning to the parameter, so it matches the baseline for well-documented schema. No extra guidance is needed beyond what the schema already provides.

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

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

The description states a specific action: 'Start or restart the measurement of a tracker against the prepaid credit balance.' This clearly distinguishes the tool from siblings like pause_tracker (opposite action), create_tracker (creation), and survey_now (immediate survey trigger). The verb+resource+scope is fully specified.

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 for when the tool is used (starting or restarting measurement) and provides explicit guidance on handling the insufficient_credits error by giving the top_up_url to the user. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for correct 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?

The description goes far beyond the sparse annotations by detailing side effects: debit of prepaid credit, the point being marked on_demand, and the next scheduled survey keeping its date. It also discloses concurrency behavior and specific error responses (insufficient_credits with top_up_url, tracker_not_active). These details are essential for safe use and are not present in 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 long but each sentence earns its place, covering purpose, side effects, concurrency, and errors. It is front-loaded with the core action and structured logically. A slight redundancy exists in explicitly listing 'same anchor, same frequency' when 'settings stay as they are' would suffice, but overall it is appropriately concise 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?

Despite lacking an output schema, the description tells the agent exactly what to expect: the answer contains a survey id, and how to retrieve results. It also covers prerequisites (active tracker), side effects (credit debit), error handling (top_up_url), and concurrency. This is a complete picture for an action with significant side effects.

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 already provides a clear description of tracker_id with a lookup hint. The tool description adds meaningful context by explaining that the tracker must be active and that credit balance affects the call, which helps the agent understand the parameter's role beyond its mere 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?

The description opens with a specific verb and resource: 'Run one survey of a measuring tracker right now, on top of its schedule.' It clearly distinguishes itself from siblings like start_tracker and get_results by explaining that it triggers a one-off survey while preserving the existing 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?

The description explains when to use the tool (to run an immediate one-off survey) and provides explicit guidance on alternatives and follow-ups: use get_results or get_responses to read the survey answer, and start_tracker first if the tracker is not active. It also clarifies that repeated calls while a survey is running answer the existing survey, preventing accidental duplicate surveys.

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 state readOnly=false and idempotent=true, and the description aligns with these while adding extensive behavioral context: batch rejection on unknown items, canon stamping requirements, site-wide item semantics, refusal to set aside the last canon cell, and the impact on ALIGNED status. It clearly discloses error conditions and side effects 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 description is lengthy but every sentence carries operational meaning. It is front-loaded with the core action and then details moves, constraints, and edge cases. It could be better structured with paragraphs or bullets, but it avoids redundancy and earns its length.

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

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

For a mutation tool with no output schema, the description thoroughly covers input semantics, failure modes, and side effects on checklist state and ALIGNED status. It does not explicitly describe the return value (e.g., what the updated checklist looks like), but given the idempotent, batch-oriented nature, the absence is not critical. The context provided is enough 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 coverage is 100% and the schema already describes each parameter well. The description adds higher-level semantics: the three moves (verify/set aside/clear), the meaning of omitted done/dismissed, the requirement of reason when dismissed, and the language handling for per-language vs site-wide items. This goes beyond what the schema alone provides.

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

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

The description opens with a specific verb and resource: 'Record what a surface actually carries, cell by cell, as many moves as you want in one call.' It clearly distinguishes this tool from siblings like add_surface_check and update_surface_check by focusing on ticking checklist cells rather than defining checks.

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 workflow: items come from list_surfaces, customer checks are added via add_surface_check, and this tool records verdicts. It gives guidance on when to verify, set aside, or clear, and warns against leaving cells untouched. However, it does not explicitly name alternative tools for when to use them instead, such as updating a check definition.

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 (readOnly=false, not idempotent), so the description carries the burden. It transparently discloses that nothing is charged by this call, payment happens at the hosted link where the user approves the amount, balance updates automatically after payment, and paused trackers resume. These are significant behavioral disclosures beyond what the annotations provide.

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 somewhat long but every sentence carries functional decision guidance. It's front-loaded with the core purpose and payment behavior first, then param selection rules, then the minimum. While dense, the content justifies its length; a rare case where verbosity serves the agent's decision-making.

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 involves money handling and has no output schema, so the description must cover return behavior (payment_url, hosted payment link) and the post-payment state changes. It covers currency handling, minimums, suggestion-sourcing, and mutual exclusivity of params. Given the stakes (financial transaction preparation), this is thorough and complete for a prepaid top-up flow.

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 rich descriptions for both parameters (major vs minor units, examples like 50→50.00, 5000→50.00). The description adds decision guidance not in the schema: when to send which parameter, that they're mutually exclusive, and that amount should match exactly what the user said. This adds genuine routing 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 clearly states the verb (prepare top-up), the resource (prepaid credit balance), and the mechanism (returns hosted payment link). It distinguishes itself from siblings by being the only tool that handles payment/prepaid credits, and explicitly clarifies that nothing is charged by this call—a non-obvious behavioral detail that differentiates it well.

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?

Excellent guidance: explicitly states when to pass `amount` (when the user names an amount) vs `amount_minor` (when the user leaves it to you and you pick from suggested_topups from get_credits). It names the alternative source (get_credits), gives exclusions (never convert currencies, never compute, never send both), and references the sibling get_credits in a helpful way. Also states the minimum.

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 idempotency and non-destructiveness. The description adds crucial behavioral nuances: null clearing for some fields but preserving for others, field dependencies, and invoice effects. No contradictions.

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 well-structured sentences, front-loaded with the main directive. It covers key points without excessive verbosity, though it could be slightly more concise.

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 6 parameters, no required fields, and no output schema, the description effectively explains null behavior, field dependencies, and business logic (invoices). It could mention the response format, but it is largely complete for a mutation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining null clearing behavior, the requirement to send billing_country with billing_address and VAT number, and invoice impact. This enhances understanding beyond schema descriptions.

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

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

The title and description clearly state 'Change the settings of the account', which is a specific verb+resource. The sibling list includes 'get_account_settings' for reading, so this tool is well-distinguished as the write counterpart.

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 explicit guidance: send only changed fields, null behavior differs per field, billing_country must accompany address/VAT. It could be improved by explicitly stating when not to use this tool, but the current instructions are thorough for typical use.

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 rich behavioral detail beyond the annotations: empty label reverts to derived, empty notes/published_on clears, URL recomputation keeps source in sync, and monitoring details including cost, state semantics, and 409 error conditions. This is far more than the annotations alone convey and gives the agent a complete safety and side-effect profile.

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 carries operational value: field-level update behavior, URL/source coupling, monitoring inclusion, and the archive alternative. It is well-organized, front-loaded with the core purpose, and avoids redundancy with the schema.

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

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

Given the tool's complexity (7 parameters, partial update semantics, monitoring side effects, error conditions), the description covers all key aspects: what changes, what clears, what recomputes, cost/state, and when to use a different tool. No output schema exists, but the description does not need to explain return values for a mutation tool, and the provided guidance is complete for safe 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?

The schema already describes all parameters with 100% coverage, giving a baseline of 3. The description adds extra meaning beyond the schema, such as clarifying that an empty notes or published_on clears those fields (not in schema) and that correcting the URL always recomputes the source. This extra context justifies 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 verb 'Update' and the resource 'the sheet of a corroboration', then explains exactly which fields change and how. It explicitly distinguishes itself from the sibling tool 'archive_corroboration' for the 'page is gone' case, making its scope unambiguous.

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

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

It explicitly says 'To say a page is gone, use archive_corroboration instead' and explains that editing never takes anything down, which is a clear when-not/alternative. It also notes that monitoring is handled by this tool, so no separate watching tool is needed, giving clear context for when to use this update.

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 idempotentHint=true. The description adds context: partial updates, clearing notes with empty string, and that only manual entries are editable. It does not contradict annotations. Minor gap: no mention of permissions or 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?

Two efficient sentences that front-load the core action and partial update characteristic. No unnecessary words; every sentence earns its place.

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

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

With 5 parameters and no output schema, the description covers the main semantics, partial update, and restrictions. A minor addition could mention idempotency implications, but overall complete enough for an experienced 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?

All parameters have schema descriptions (100% coverage). The description adds value beyond schema by explaining the partial update semantics for 'notes' and the date computation guidance for 'occurred_at'. A baseline of 3 is appropriate, and the extra context raises it to 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 verb 'Edit' and the resource 'manual logbook entry', and distinguishes from siblings by specifying that only manual entries can be edited, not tool events.

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 partial update behavior ('only the fields you send change') and a specific case ('empty notes clear them'). It also states that tool events cannot be edited, implicitly guiding when not to use. Could explicitly mention alternatives but is 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?

Beyond annotations (idempotentHint true), the description explains that identical wording records nothing, empty strings clear fields, omitted fields are kept, and each actual change creates a new immutable numbered version with version_created in the response. It also details language constraints and downstream effects, providing substantial 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 about 120 words but packs in essential behavior: update semantics, versioning, language, stability, and confirmation. It is well-structured with clear sentences, each adding value without 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 tool with 13 parameters and no output schema, the description covers key contextual aspects: versioning response flag, language behavior, and user confirmation. It could additionally mention prerequisites like project existence, but the schema already instructs to call list_projects for project_id. Overall, it is comprehensive for its 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?

The schema covers 100% of parameters, but the description adds critical cross-parameter semantics: field-by-field replacement, empty-string clearing, omitted-kept behavior, and the requirement that canon_language must be sent with at least one wording until the canon is posted. This meaningfully deepens understanding 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 opens with 'Revise the brand canon of a project,' using a specific verb and resource. It clearly distinguishes this from sibling update tools by focusing on the canon specifically and explaining the field-by-field revision model.

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 instructs 'Confirm with the user before revising' and states the canon is meant to be stable and revisiting is rare and deliberate. This gives clear context for when to use the tool, though it does not explicitly name alternatives or exclusions beyond that.

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?

Discloses partial update (only fields sent change) and empty notes clearing behavior. Aligns with annotations (idempotentHint=true, destructiveHint=false) without contradiction.

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 efficiently convey purpose, key behavior, and exclusions. 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 update tool with 3 well-documented parameters and no output schema, the description provides all necessary context for correct usage.

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 covers all parameters. Description adds value by explaining the clearing behavior for notes and reinforcing title semantics, but beyond that it is not extensive.

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 'Edit a quest' and explains partial update behavior, distinguishing it from status-changing 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?

Explicitly says when to use (simple edits, corrections) and when not (status changes), naming alternative tools like complete_quest, dismiss_quest, reopen_quest.

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 annotations, the description discloses detailed side effects: language replacement, label/notes clearing, column renaming, dropped_checklist_columns behavior, persistence of cells, and the derived status. This is far richer than the idempotentHint and readOnlyHint annotations, providing valuable 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 longer than typical but well-structured: it starts with the core action, then explains behavioral nuances in a logical flow. Each sentence provides meaningful detail without redundancy, though it could be tightened slightly without losing value.

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 (language list replacement, column handling, dropped columns), the description covers key behaviors and return aspects (dropped_checklist_columns, read-back advice). It does not describe the exact response schema, but no output schema exists and the description provides sufficient guidance for an agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds some conceptual context (e.g., languages as columns, dropped_checklist_columns) but does not significantly enhance parameter-level meaning beyond what is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Update the registry sheet of a surface' with a specific verb and resource. It also distinguishes from siblings by explicitly noting that no journal line is written and that alignment is earned via tick_surface_checklist, making its scope 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?

Provides explicit guidance on how updates work ('only the fields you send change'), when to use alternative tools ('No journal line is ever written here... tick_surface_checklist'), and what to check after updating ('read it back rather than assuming it held'). It does not enumerate all alternative tools but gives clear contextual cues.

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 a significant side effect: setting restates_canon to true causes ticks without a canon stamp to 'perish,' which is destructive behavior. This directly contradicts the annotation destructiveHint=false, which would lead an agent to believe no data destruction occurs. Therefore, the description contradicts annotations and must be flagged.

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 earning its place: purpose, partial-update behavior, and the critical restates_canon side effect. It is front-loaded with the main action and uses clear examples to explain consequences. 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?

The description is thorough for a 4-parameter update tool: it covers the purpose, the partial update model, key immutability, and the only notable side effect. It does not describe the return value, but no output schema exists and the tool's result is likely trivial. However, the annotation contradiction introduces confusion about the tool's safety profile, preventing a perfect completeness score.

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