Epovest

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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds important behavior: the mutation effect (keyword added, series starts next survey), the all-or-nothing batch behavior, and specific error responses. It does not cover authentication or rate limits, but the key behavioral traits are 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 three sentences, front-loaded with the main purpose, and every sentence adds value. No redundancy or 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 tool has 3 parameters and no output schema. The description explains the output shape (keyword for single, keywords for batch) and covers error cases. It is sufficient for this simple tool, though it could mention more about the return format.

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: the mutual exclusivity of 'domain' and 'domains', the all-or-nothing behavior of the batch, and the consequence of acceptance (tracked keyword, series starts). 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 verb 'Accept' and the resource 'discovered suggestion (domain) or a batch (domains)'. It explains the outcome: each becomes a tracked keyword and its series starts at the next survey. This distinguishes it from sibling tools like 'dismiss_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 provides clear context: 'Accept on behalf of the user only when they said yes.' It also explains error conditions (keyword_cap_reached, not_found) and batch behavior. However, it does not explicitly state when not to use or list alternative tools for similar actions.

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: 'Nothing is deleted: the line stays, and so does the history' and 'A page taken down stops counting as a presence on that source.' Annotations already indicate non-destructive, but description elaborates meaningfully.

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 (4 sentences), front-loaded with the action, and each sentence adds necessary context without unnecessary words. It is well-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?

For a simple toggling tool with 2 parameters, no output schema, and annotations present, the description is complete. It explains the effect, non-destructive nature, and usage requirement.

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 already covers both parameters with complete descriptions. The tool description does not add new semantic information about parameters beyond what the schema provides. Schema coverage is 100%, 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 title and description clearly state the tool toggles archived status of a corroboration. It specifies 'take down' or 'put back live', distinguishing it from creating or updating corroborations.

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 usage guideline: 'Only take down after actually re-reading the address and finding it gone.' It implies when to use this tool vs alternatives, though not explicitly listing 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 goes well beyond annotations: it explains that archiving moves the project to the end of the list, sets archived to true, stops it from being offered when filing trackers, that nothing is deleted, no cascading effects, the return includes tracker_count, and that re-archiving an already archived project yields the same result. This fully discloses behavior for an agent.

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

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

The description is lengthy but every sentence adds meaningful information. It is front-loaded with the primary purpose and usage context. Could be slightly more concise, but readability is good.

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, yet the description explains the return value (tracker_count) and covers edge cases (already archived, default project). It provides complete context for an agent to understand the tool's full behavior and 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 coverage is 100%, so parameters are already documented. The description adds value by clarifying the default behavior for archived (true if omitted), the source of project_id (list_projects), and the implication of the default project (no id). This provides extra context 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 description clearly states the action ('File a project away') and specifies the resource ('a project'). It distinguishes from sibling tools like archive_tracker by explicitly stating that trackers are not affected. The use cases (client left, brand sold) provide concrete 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?

The description explicitly says when to use this tool ('once the folder has served its purpose') and what not to use it for (tracker archival). It provides guidance on how to bring projects back (archived false) and mentions the alternative tool (archive_tracker) for archiving trackers individually.

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 key behaviors: moving to list end, pausing measurement, stopping spending, and that sheet and scores remain readable. This adds value beyond the annotations, which indicate destructiveHint=true but the tool is reversible. 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?

The description is well-structured and front-loaded with the main action. Four sentences, each adding value, though 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 the lack of output schema and moderate complexity, the description covers essential effects and reversibility. It does not mention error cases or authentication, but overall sufficiently complete.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the effect of the archived boolean and how to find tracker_id via list_trackers. This goes beyond the schema's 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 purpose: to file a finished tracker away. It uses a specific verb ('file away') and resource ('tracker'), and distinguishes from siblings like pause_tracker by specifying it's for finished trackers and changes the list ordering.

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 (for finished trackers) and explains reversal via archived=false. However, it does not explicitly contrast with pause_tracker, though the 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?

The description goes well beyond annotations. It explains idempotency (calling again is safe), the effect on dismissed quests (becomes done), and that the quest remains readable. These details are critical for an agent to understand side effects and safety, and no contradictions with annotations 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?

The description is two sentences with no wasted words. It front-loads the core action ('Mark a quest done') and efficiently conveys idempotency, edge cases, and persistence. 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?

Given the tool's simplicity (mutation, 1 param, no output schema), the description covers the behavioral effects well. It lacks explicit mention of return values, but that is minor. The description, combined with schema and annotations, provides sufficient 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?

The input schema has 100% description coverage for the single parameter (quest_id). The description adds no additional semantic meaning beyond what the schema already provides. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool 'marks a quest done' with specific actions (sets state and closing date). It distinguishes from sibling tools like dismiss_quest and update_quest by focusing on completion. The verb 'complete' in the name is reinforced by 'done', providing unambiguous purpose.

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

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

The description implicitly guides usage by explaining idempotency and the handling of dismissed quests (the last move wins). It does not explicitly contrast with peers like dismiss_quest or create_quest, but the context of completing vs dismissing is clear. A more explicit 'use when...' would elevate this score.

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 message lands in support threads seen in app, human replies, and behavior of subject derivation and thread_id usage. No contradiction with annotations. Could mention limits but not necessary.

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

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

Four sentences efficiently cover purpose, usage, behavior, and parameter details 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?

Complete for a simple communication tool: explains what happens after sending, how to check replies via get_support_thread, and references sibling tools for thread management.

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 100%, description adds meaningful guidance: message content advice, kind's sorting purpose, subject derivation/reply behavior, thread_id usage with link to sibling.

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?

Describes sending a message to human support with specific use cases (report problem, suggest, ask question). Explicitly distinguishes from sibling get_support_thread for reading replies.

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 (tool refusal, missing product, user request). Explains how to reply to existing thread and directs to list_support_threads for finding thread_id.

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 sparse (no readOnly, destructive, etc.), so the description carries the burden. It discloses that the tool is a statement of fact, describes three possible error outcomes, and indicates idempotency via the duplicate refusal (409). While it doesn't cover all behavioral traits (e.g., no mention of rate limits or authentication), it provides solid behavioral context 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 a single dense paragraph, but every sentence adds value. It could be slightly more structured (e.g., bullet points for refusal slugs), but it is concise and not 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?

Given no output schema, the description doesn't explain return values, which is a minor gap. However, it covers error slugs and critical usage constraints. For a creation tool with 5 parameters and no nested objects, it is largely complete and addresses the main concerns an agent would have.

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. The description adds meaning: URL-first (implied order), label derived from URL, notes are free text, project_id from list_projects, published_on distinct from recording day and never guessed. This enriches understanding 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 clearly states 'Record that a third-party page talks about the brand', which is a specific verb and resource. It distinguishes from siblings like create_surface (for own domain) and archive_corroboration, making the purpose unmistakable.

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: the exact address of the page is the only thing needed', advises to only record pages actually read and confirmed with user, and provides three refusal reasons (unplaceable_url, own_domain, duplicate) with concrete actions (e.g., use create_surface for own_domain). This level of guidance is exceptional.

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 states 'Recording is idempotent on the project, the label and occurred_at', but annotations set idempotentHint: false, a direct contradiction. This severely undermines transparency.

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 adds value, covering purpose, idempotency, and parameter semantics. Slightly long but well-structured and front-loaded with the key 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 output schema, describes what happens (entry joins logbook, lands as annotation). Covers idempotency and temporal nuance. Adequately complete.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: clarifies occurred_at refers to action time, not recording time, and explains label's role in annotations.

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 records an action in the logbook of a project, with specific verb and resource. Distinguishes from sibling tools like delete_logbook_entry and update_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?

Explains the normal use case (recording after the fact) and idempotency making retries safe. Does not explicitly mention when to avoid using it or alternatives, 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?

Discloses that the tool is a creation (not readonly), idempotent behavior on duplicates (refuses with project_exists and returns existing project id), and that parameters like canon_perks replace previous ones. Annotations are consistent, and the description adds context beyond 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 concise, packing essential rules and context into a single paragraph. It is front-loaded with purpose and constraints. Could be slightly more structured (e.g., bullet points), but remains efficient without 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?

Given the complexity (13 parameters, no output schema), the description covers creation rules, duplicate handling, and post-creation usage. It mentions the returned id for later use, which partly compensates for missing output schema. Some additional details about response format could be useful, but not required.

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

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

Schema coverage is 100%, but the description adds conceptual meaning: explains canon as reference wording in one canonical language, never translated, and that canon fields like canon_perks are not just any claims but verifiable facts. This enriches the schema's descriptive text.

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

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

The description clearly states this tool creates a project for filing trackers, with the specific rule 'one project per BRAND, never per language.' It distinguishes itself from siblings like archive_project or update_project_canon by explaining the project's role and constraints.

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 (for a brand), what not to do (never per language), and what to do on duplicate (reuse existing project id). Also clarifies that trackers are not filed by this call, guiding the user to use the returned id later.

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 reveals critical behavioral traits beyond annotations: conditional idempotency (safe retry for open quests), behavior for closed quests (not blocked), and that calling again returns existing quest. This adds significant context beyond the idempotentHint: false annotation.

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 but includes some repetitive detail. It is front-loaded with the main action and uses an example to clarify usage. Minor trimming could be possible, 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?

Given no output schema, the description covers all necessary aspects: what the tool does, when to use it, idempotency behavior, and handling of closed quests. It is complete 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the semantics of 'title' (the move wording) and 'notes' (context and links), reinforcing the schema descriptions and tying them to the tool's purpose.

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

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

The description clearly states the tool's function: 'Add a quest to the file of a project: a next move the customer decided...' It uses specific terminology (quest, project file) and distinguishes it from siblings by focusing on creation.

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 (when a customer decides a next move) and mentions idempotency behavior for open quests, providing safe retry. However, it does not explicitly state when not to use it or compare with alternatives like update_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?

Adds behavioral context beyond annotations: the surface is 'born never_aligned' and requires explicit alignment via mark_surface_aligned. No contradiction with annotations. The description provides useful workflow 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?

Relatively concise but uses metaphorical language ('born never_aligned', 'in phase with the canon') that may be confusing. Could be more direct while retaining essential 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?

Mentions the need to later mark_surface_aligned but does not fully explain the lifecycle or checklist. For a creation tool with 6 parameters and no output schema, more detail about next steps and return value 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 description coverage is 100%, so baseline is 3. Description adds value by emphasizing URL-FIRST, explaining derivation of type and label, and when to override. Adds 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?

Clearly states 'Register a surface of a project' and explains what a surface is. The description distinguishes the tool from siblings like update_surface, delete_surface by focusing on creation and the URL-first approach.

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 guidance on omitting type and label on creation, only passing them to correct derivation. However, it does not explicitly state when not to use this tool or compare to alternatives; the context is implied but not exhaustive.

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

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

Annotations show no readOnly, idempotent, or destructive hints. The description adds that the tracker is in draft and measures nothing, and that first survey runs at start_tracker if next_survey_at omitted. It does not disclose credit consumption or side effects like whether creation can be undone. This is moderate additional 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?

Three sentences, each serving a purpose: creation state, action needed, and a parameter default. No fluff, but could be more structured with bullet points for complex parameters.

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 12 parameters, 5 required, and no output schema, the description is too brief. It does not mention what is returned (e.g., tracker ID), nor explain the overarching purpose of trackers or the project context. Users would need to infer much from the schema.

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

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

Schema covers 100% with parameter descriptions. The description adds one key insight about next_survey_at defaulting to start_tracker time. No other parameter nuances are provided, so value over schema is minimal.

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 creates a tracker in draft and distinguishes from start_tracker by noting it measures nothing yet. However, it does not differentiate from update_tracker or pause_tracker, missing some sibling 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?

Provides explicit guidance to call start_tracker after creation and mentions validation rules from the app configurator. But lacks when-not-to-use scenarios or comparisons to other siblings like update_tracker.

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 (destructiveHint=true), the description reveals that the entry goes to trash (restorable), removes associated annotations, and that tool events are preserved. This adds valuable context about side effects and reversibility.

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

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

The description is four sentences and contains some redundancy ('Only do it when the user asked for it: it is their logbook' could be shortened). It is clear but not as concise as it could be.

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 deletion tool with one parameter, the description together with the schema provides adequate context: what happens to the entry and annotations, restore capability, and non-impact on events. No output schema needed.

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 referencing get_logbook. The description does not add additional parameter semantics beyond what the schema already 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?

Description clearly states the action: 'Take a manual logbook entry out of the logbook' – a specific verb and resource. It also distinguishes from sibling tools like restore_logbook_entry, providing clear 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?

The description says 'Only do it when the user asked for it: it is their logbook' but lacks explicit when-not-to-use guidance or comparisons to alternatives like update_logbook_entry. It does mention restore_logbook_entry as a recovery path, which helps, but overall guidance is limited.

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 (destructive, idempotent), explains what is preserved (sheet, alignment journal) and that restoration is possible, adding non-obvious 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?

Description is well-structured and front-loaded with action and outcome. It is concise but contains necessary details; slightly longer than minimal but 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 single parameter, no output schema, and destructive yet idempotent behavior, the description covers all relevant aspects: action, use cases, side effects, and reversion possibility.

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 the single parameter fully; description adds no extra meaning beyond the schema's description. 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 tool removes a surface from registry, stopping tracking and canon alignment. It specifies use cases (page gone or misplaced) and distinguishes from restore_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?

Explicitly states when to use (page gone, line misplaced) and that taking out an already taken out surface is safe. References restore_surface as the alternative.

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

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

Annotations already indicate idempotent=true and destructive=false. The description adds that the page 'is never proposed again for this project', clarifying the permanent effect. It also notes 'Nothing is created or deleted', aligning with annotations and providing additional 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 extremely concise: two sentences with the core action, usage guidance, and alternative immediately provided. No wasted words, and the critical information is front-loaded.

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

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

Given the simple two-parameter tool with no output schema, the description covers the purpose, usage context, effect, and relationship to the accept action. It is fully complete for an agent to understand and 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?

Schema coverage is 100% and both parameters are well described in the input schema (url format, project_id UUID). The description does not add any extra parameter semantics beyond what the schema provides, 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 it refuses a suggested page and that the page is never proposed again for this project. The verb 'refuse' and resource 'corroboration candidate' are precise, distinguishing it from the sibling 'create_corroboration' which accepts.

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 ('when the excerpt matched something else than the brand, or when the page is not worth recording'), when not to use, and provides the alternative ('Accepting is the opposite move and has no tool of its own: call create_corroboration with the url of the candidate').

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 adds that dismissing an already dismissed domain is fine, and explains the all-or-nothing batch failure on unknown domains. It also describes the response format (dismissed domain or list). These details provide useful 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 a single paragraph that efficiently covers purpose, behavior, batch rules, and response. It could be slightly more structured (e.g., separate sentences for single vs batch), but it is clear and to the point.

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 3 parameters and no output schema, the description covers the effect, error handling (all-or-nothing), idempotency, and response. It leaves no major gaps for an agent to misunderstand the tool's behavior.

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

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

With 100% schema coverage, baseline is 3. The description adds critical context: domains must be listed exactly as in list_keyword_discoveries, and explains the all-or-nothing rule for batches. 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 dismisses one or multiple domains (keyword discoveries) and explains the effect: they are never proposed again on the tracker and appear on the dismissed list until restored. This distinguishes it from siblings like accept_keyword_discovery or restore_keyword_discovery.

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 does not explicitly state when to use this tool versus alternatives (e.g., accept or restore). It does provide guidance on batch behavior and all-or-nothing semantics, but lacks context on when dismissal is appropriate compared to other actions.

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 key behavioral traits beyond annotations: it sets the state and closing date, retry is safe (idempotent), the quest remains readable in closed history, and adding it again later starts a new quest. This aligns with annotations (idempotentHint=true, destructiveHint=false) and provides complete transparency.

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 long, front-loaded with the core action, and every sentence adds value (purpose, idempotency, post-action behavior). No extraneous information is present.

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 what the tool does, its effects, retry safety, persistence, and re-opening behavior. No additional context is needed.

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 covers 100% of parameters (only quest_id) and includes its description ('call list_quests to find it'). The tool description does not add further parameter-specific meaning, so a baseline score of 3 is appropriate as the schema already carries the burden.

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 primary purpose: 'Set a quest aside: the customer decided the move is off.' It specifies the action (dismiss) and the context (customer cancels), and distinguishes itself from other quest-related tools like 'complete_quest' by indicating it marks the quest as dismissed rather than completed.

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 ('the customer decided the move is off') and notes that retrying is safe, implying idempotent usage. However, it does not explicitly state when not to use this tool or compare it to alternatives such as 'complete_quest' or 'archive_project', leaving the agent to infer the appropriate scenario.

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 significant behavioral details about what information is returned (available credits, reservations, expiration, data-access window). No contradiction, and it complements the annotations effectively.

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 waste. The first sentence front-loads what the tool returns, the second provides usage context. Perfectly sized for an 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?

No output schema, so the description must cover return values. It does so thoroughly, listing available credits, reservations, expiration, and data-access window. Combined with usage context, it is complete for a read-only balance check 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?

The input schema has no parameters, so the description does not need to add parameter information. It explains the output content well, which is appropriate for a zero-parameter tool. Baseline 4 is justified.

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 the prepaid credit balance, including specific details like available credits, reservations, expiration, and data-access window. The verb 'get' matches the name, and it is distinct from sibling tools like 'topup_credits'.

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 usage guidance: 'Read it before starting a tracker, or when a call fails with insufficient_credits or data_access_expired.' This tells the agent when to use the tool, though it doesn't mention 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 declare readOnlyHint=true, and the description adds rich behavioral details: logbook composition, field meanings (occurred_at vs published_on), and 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 information-dense in a single paragraph, which is functional but could be better structured. Every sentence adds value, though the format could be clearer for quick scanning.

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 no output schema, the description covers return structure (fields like id, category, label, notes, occurred_at, published_on, deleted_at) and composition. It is fairly complete given the tool's complexity, though it could mention pagination or limits.

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 meaning beyond schema: explains source values, category filtering, deleted behavior, and the relationship between occurred_at and published_on. This enriches the schema 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?

The description clearly states the tool reads the logbook of a project, newest first, combining two sources. It distinguishes from sibling tools like create_logbook_entry, delete_logbook_entry, and restore_logbook_entry by focusing on reading.

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 see what was done when curves moved. It also covers special behavior for deleted='only' to read trash. However, it does not explicitly contrast with other read tools like get_source or list_corroborations.

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

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

Annotations mark it read-only; the description confirms read-only behavior. It adds details about pagination, response structure (cited/uncited sources, searched field), and the heavy nature of include_raw. 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?

The description is concise (one sentence), front-loaded with purpose, and includes all key information without redundancy. Every word 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?

For 8 parameters and no output schema, the description covers the main behavior and special fields. It does not detail pagination mechanics (schema does) or the full payload format, but is adequate 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%, baseline 3. The description adds context beyond schema by explaining the meaning of uncited_sources and searched, and warning about include_raw. It does not explain every parameter individually but provides sufficient 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 it returns raw answers for one AI engine and a tracker, with pagination and ordering (newest first). It clearly distinguishes from sibling tools like get_results.

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 when to set include_raw (only when needed) and explains the returned fields (cited sources, uncited_sources, searched). However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds behavioral context by detailing the output structure (rows and columns) and how data varies by analyst, which goes beyond the 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?

The description is two sentences, front-loading the purpose and efficiently summarizing the output structure and column variation. Every sentence adds value, and there is no extraneous information.

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

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

Given no output schema, the description explains the return structure adequately (rows by dimensions, columns by analyst). It covers the key aspects needed for a read-only retrieval tool, though it could mention pagination or error conditions. Overall complete for typical use.

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 input schema already documents all parameters with descriptions. The tool description does not add new meaning beyond the schema, thus 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 retrieves the score series of a tracker, specifying the structure (one row per analyst, keyword, engine, tracker version, and survey period) and the varying columns per analyst. It distinguishes from siblings like get_responses (raw responses) and list_trackers (tracker metadata).

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

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

The description implies usage when needing the score series but does not explicitly state when to use this tool versus alternatives like get_responses or list_trackers. No exclusions or prerequisites are mentioned.

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. The description adds behavioral context by specifying the returned data (domain and AI Authority), which goes 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?

Two sentences, no fluff, efficiently conveys purpose and usage.

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 values. For a simple read-by-id tool with robust annotations, this is complete.

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

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

Schema coverage is 100% and the description adds a helpful note on finding the UUID via list_sources, adding meaning beyond the schema's description.

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

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

The description clearly states the tool reads one entry of the Atlas by its id, specifying the content (domain and AI Authority). It distinguishes from list_sources by mentioning its specific purpose.

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

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

Explicitly tells when to use this tool vs list_sources: call list_sources to find the id, or to read filtered/ranked entries. Provides 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 already declare readOnlyHint=true, and description aligns by stating a read operation. The description adds value by specifying that messages include support team answers and the intended usage pattern, which is 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?

Two concise sentences with no redundant information. First sentence immediately states the core purpose and returned data, second sentence provides usage context. 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 single parameter with full schema, clear annotations, and no output schema needed (return is a thread with messages), the description fully covers what an agent needs to invoke correctly: what it returns, when to use it, and how to find the thread ID.

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

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

Schema coverage is 100% with a clear parameter description for thread_id. The tool description does not add new parameter semantics beyond referencing usage context. Baseline 3 is appropriate as schema already documents the parameter fully.

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

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

Description explicitly states 'One support thread with its messages, including the answers of the support team', clearly defining verb (get/read) and resource (support thread with messages). It distinguishes from sibling list_support_threads by focusing on a single thread with content.

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 'Read it back after contact_support to relay the answer to the user', providing clear when-to-use context and purpose. Parameter description also references list_support_threads for finding the ID, offering discovery 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?

Goes well beyond annotations (readOnlyHint, openWorldHint) by explaining recomputation, raw payloads, surveys_scanned field, and semantics of matched_by field. 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?

Front-loaded with purpose, then details in logical order. Slightly long but every sentence adds value; no waste.

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

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

Complete for a read-only list tool with no output schema: explains row contents (excerpt, matched_by, surveys_scanned) and their meanings. Provides enough 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?

Only parameter is project_id, already well-described in schema (UUID, list_projects). Tool description adds no extra meaning beyond 'call list_projects to find it'. Schema coverage 100%.

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 lists pages where search engine showed the brand, with concrete verb 'list' and resource 'corroboration candidates'. Distinguishes from siblings by explaining when to use create_corroboration and dismiss_corroboration_candidate instead.

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 describes the behavior: nothing fetched/stored, recomputed from raw payloads, and how to accept/refuse candidates. Provides context for when to use this read-only list, though could more explicitly contrast with list_corroborations.

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, so no mutation. The description adds that results are ordered live first then archived, and that data is customer-declared. This provides useful behavioral context beyond the annotations.

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

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

The description is thorough but somewhat lengthy. It is front-loaded with the core function and includes useful comparisons. Every sentence adds value, 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 the simple parameter, full schema coverage, and no output schema, the description explains what the output contains (address, source, publication date, notes, archived status) and the ordering. This is fully complete for an AI 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 single parameter project_id has 100% schema description coverage. The description adds that it's a UUID and suggests calling list_projects to find it, which provides helpful guidance 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 specifies the tool lists corroborations (third-party pages about the brand) for a project, with ordering by live/archived. It clearly distinguishes from siblings list_surfaces (what the brand writes) and list_corroboration_candidates (suggested pages).

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 context: it lists declared corroborations, while list_corroboration_candidates proposes pages from engines. It also contrasts with list_surfaces for the brand's own content, giving clear alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. Description adds that results are 'recomputed on every read' and includes dismissed domains, which is behavioral context beyond annotations. 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 information-dense yet not overly long. It front-loads the core purpose and then explains the lists and user guidance. Each sentence adds value, though slightly longer than minimal.

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 parameter and no output schema, the description fully explains what the tool returns (two lists, disjoint) and how it behaves (recomputed on read). Includes user guidance on decision-making. Complete for 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 has 100% coverage for the single parameter tracker_id with its own description. The tool description adds context by mentioning 'on a tracker', linking to the parameter's purpose. Baseline 3, extra credit for linking parameter to overall function.

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 'List' and resource 'discovered keyword suggestions', explaining what 'discovered' means (domains cited by engines not covered by tracked keywords). Distinguishes from siblings like dismiss_keyword_discovery and restore_keyword_discovery by mentioning dismissed and restore functionality.

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: to see discovered suggestions for a tracker. Describes the two lists (discovered and dismissed) and their disjoint nature. Does not explicitly mention when not to use, but the context is clear given the sibling tools.

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

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

The description fully discloses behavioral traits: idempotent read-only operation, ordering by usage status, and the existence of a virtual Default project. The annotations already indicate readOnlyHint=true, and the description adds valuable context beyond that 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 three sentences, each serving a purpose: defining the resource, listing output properties, and explaining ordering and default project. No redundancy or fluff.

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 zero-parameter list tool with no output schema, the description is completely sufficient. It explains the purpose, output fields, and ordering, leaving no ambiguity about what the tool returns or how it behaves.

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 no parameters, so the baseline is 4. The description adds significant value by detailing the output fields (id, name, brand canon with version, archived flag, tracker count) and ordering, which compensates for the lack of param documentation.

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 lists projects, explaining what a project is (a folder for trackers) and distinguishing it from sibling tools like list_trackers. It explicitly mentions that projects are for pure organization with no effect on measurement or billing, setting clear boundaries.

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 on when to use this tool by defining what projects are and their role. It implies that this is the tool to retrieve project metadata, including the virtual Default project for trackers without a project. However, it lacks explicit guidance on when not to use it or alternatives like list_trackers.

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 aligns, describing a read-only listing. It adds behavioral details: defaults to open status, newest first, scoping to one project, and explains the 'pending' field's contents and related actions. 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 notably long and dense, packing extensive details about pending items and related tools. While well-structured, it could be more concise; not every sentence is essential for the core listing function.

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, no output schema, and the need to explain pending items, the description is complete. It covers default behavior, filtering, and links to sibling tools for follow-up actions.

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 meaning: status defaults to 'open', and project_id is optional with scope to one project. It explains the effect of each status value and the default project behavior.

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 specifies the verb 'lists', the resource 'quests of the account', and provides clear scope: moves decided and recorded, open by default, newest first. It distinguishes from sibling tools by mentioning related actions for pending items (list_surfaces, list_keyword_discoveries, etc.).

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

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

The description states when to use the tool: to see what to do for GEO work, pending files, and to resume. It implies when not to use by directing to other tools for specific actions (e.g., list_surfaces for surfaces). However, it does not explicitly contrast with alternatives for listing quests from other perspectives.

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 provide readOnlyHint, but description adds valuable behavioral context: scale per AI, absence not zero, registrable domain units, and data source. 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 verbose and somewhat convoluted. It front-loads conceptual explanation but could be more direct. Some sentences are unnecessary for tool selection (e.g., 'each column ranks... almost disjoint') and reduce 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?

No output schema, so description must explain returns. It describes the data model (domains with scores) but does not specify response structure or pagination details. Schema implies pagination, but description lacks explicit mention of output format.

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 3. Description adds nuance for 'sort' parameter (explaining each enum), but other parameters rely on schema descriptions which are clear. Some added value but 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 the tool lists sources from the Atlas, and explains they are domains cited by AIs with AI Authority scores. It differentiates from 'get_source' by implication (list vs single), but does not explicitly contrast with 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 implies usage for seeing where answers come from, but does not explicitly state when to avoid or provide alternatives. The context of per-account surveys is mentioned, but no exclusion 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 already indicate readOnlyHint=true. The description adds ordering (most recent first) and details on content (what was asked, answer status). This goes beyond the annotations to explain the return 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?

One sentence efficiently conveys purpose, ordering, and content. No redundant or missing 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?

The description explains the key output fields (content and answer status) and ordering. Without an output schema, this provides sufficient context for a simple list tool. It could mention thread identifiers or date, but is 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?

With zero parameters and 100% schema coverage, the description does not need to explain parameters. It appropriately describes the output structure, which is the main semantic 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 clearly states the tool lists support threads, ordered most recent first, and includes what was asked and whether answered. This specific verb+resource combination distinguishes it from siblings like 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?

The description provides context that threads are shared by account members, but does not explicitly state when to use this tool versus alternatives like get_support_thread or other list tools. Usage is implied but not guided with exclusions.

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

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

Annotations already provide readOnlyHint=true. The description adds significant domain-specific behavioral context: the derivation of surface status (never_aligned, aligned, needs_update) based on canon wording changes, and the presence of a checklist. This goes beyond the schema and annotations, aiding the agent in understanding the data model.

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 overly verbose and dense with domain-specific jargon (e.g., 'DERIVED status against the versioned canon', 'never conditions the marking'). It could be condensed to a few clear sentences. The purpose is front-loaded but the detail on status and checklist is excessive for a list tool.

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

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

Despite no output schema, the description lists the returned fields (type, url, label, languages, notes, status, checklist) and explains the deleted parameter behavior. It provides sufficient context for the agent to understand what to expect. However, it could be more structured and mention that the result is a list.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds a minor clarification for 'deleted' ('read the trash'), but this is already covered by the schema description. No additional parameter semantics are introduced.

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 'List the surfaces of a project' clearly states the action and resource. The description reinforces this with 'Start here to find a surface id' and explains the concept of surfaces. It distinguishes from sibling tools like create_surface, delete_surface, etc., by being the listing operation.

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

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

The description explicitly says 'Start here to find a surface id,' indicating this tool is the entry point before modifying surfaces. It also mentions the 'deleted' parameter variant for reading trash. However, it does not explicitly state when not to use it or when alternatives are better, though the context implies its role.

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 value by revealing the ordering (active first, then archived) and the presence of fields like archived_at and archived true. This helps the agent understand expected output structure.

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 unnecessary words, front-loaded with purpose and key details. 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?

For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose, filtering, and ordering. It could mention that it's read-only (though annotation covers that) or note related tools, but it is sufficiently 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 description explains the project_id parameter's effect (filter by project) and implies behavior when omitted (list all). Since schema coverage is 100%, this adds useful 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 verb (list) and resource (trackers), and specifies what information is included (configuration, status, keywords, analysts, project, cost per survey). It distinguishes itself from sibling tools like archive_tracker or pause_tracker by positioning it as the starting point for finding tracker IDs.

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 guidance on when to use ('Start here to find a tracker id') and how to filter by project_id. It doesn't explicitly state when not to use or list alternatives, but the context is sufficient for a typical listing scenario.

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 details beyond annotations: it freezes version and date in alignment journal, sets alignment_created true, and specifies conditions for no-op and error. No contradiction with annotations (idempotentHint true is consistent).

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. Front-loaded with core purpose then important usage conditions. 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 single parameter, no output schema, and rich annotations, the description fully covers behavior, prerequisites, and edge cases. 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?

Only one parameter (surface_id) with 100% schema coverage including format and description. The description does not add extra semantics beyond the schema, 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?

Description clearly states the tool records that a surface reuses the current project canon, specifying the verb 'Mark' and the resource 'surface aligned'. It distinguishes itself from siblings like 'update_project_canon' and 'create_surface' by focusing on a specific alignment journal action.

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 to only mark after actual page update, to confirm with user, and explains edge cases: already aligned records nothing, no canon returns no_canon. This provides clear when-to-use and 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?

The description reveals that the score series is kept, which adds behavioral context beyond the annotations. Annotations indicate idempotentHint=true and no destruction, which aligns with the description. 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 extremely concise at two sentences (15 words) and immediately states the core action. Every sentence contributes meaningful information 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 simple tool with one parameter and no output schema, the description explains the core behavior and its relationship to start_tracker. It does not specify behavior for already-paused or inactive trackers, but idempotency suggests safety.

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

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

Schema description coverage is 100%, so the parameter tracker_id is fully documented in the schema. The description adds no additional parameter-level information beyond what the schema provides, placing it 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 the action (pause measurement) and the resource (active tracker). It distinguishes from start_tracker by noting that the score series is preserved and can be resumed. This effectively differentiates it from sibling tools like archive_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?

The description implies usage for temporarily pausing an active tracker and references start_tracker as the resume counterpart. However, it does not explicitly mention when not to use it or alternative tools for permanent stops, such as archive_tracker.

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 annotation, the description adds that restoring a non-dismissed domain simply leaves it eligible and that the tool is never refused. It explains the effect on the dismissed list, adding meaningful behavioral context.

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

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

The description is concise with no redundant phrases. It front-loads the core action, then efficiently explains effects, idempotency, and batch behavior in a few sentences.

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

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

Given the simple parameters and no output schema, the description covers all necessary aspects: operation, eligibility, idempotency, batch partial failure, and return format. It is fully sufficient for correct agent execution.

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 parameter descriptions, but the description adds crucial usage guidance: send domain OR domains, never both, and the ALL-OR-NOTHING rule for batches. This provides practical 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 the tool restores dismissed domains, making them eligible for discovery again. It distinguishes itself as the counterpart of dismiss and contrasts with accept, providing specific verb and resource with sibling differentiation.

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

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

The description explicitly says it is for when the user changes their mind after dismissing, giving clear use case. It lacks explicit when-not-to-use or alternative comparisons beyond dismiss, but the 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 already declare idempotentHint=true and destructiveHint=false. Description adds that restoration includes the annotation placed on curves, and confirms idempotency in words. No contradictions. Adds value beyond annotations by describing the side effect on curves.

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

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

Two sentences, each essential. No fluff or repetition. Front-loaded with the primary action, then deployment guidance.

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

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

For a simple one-parameter tool with no output schema and strong annotations, the description fully covers how to find the entry, what will be restored, and the idempotent behavior. 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?

With 100% schema description coverage, baseline is 3. The description adds useful context: it specifies the parameter format (UUID) and instructs to call get_logbook to find the entry, including a caveat that only manual entries carry an id. This goes beyond the schema by providing discovery method.

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 an entry back to the logbook') and the resource ('logbook entry') with specific context about restoring annotations. It distinguishes from sibling tools like delete_logbook_entry and create_logbook_entry by implying a restoration operation.

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

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

Provides explicit guidance to use get_logbook with 'deleted' set to 'only' to find deletable entries. Also notes idempotency ('Restoring an entry already in the logbook answers the same'). Does not explicitly mention when not to use, but the context is clear.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description confirms idempotency and adds specifics: the restored surface includes its sheet and alignment journal 'as they were'. It does not disclose permissions or side effects, but with good annotation coverage, this is acceptable.

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: the first clearly states the core action, the second provides a practical prerequisite and idempotency note. Every sentence is essential and front-loaded, with no redundant wording.

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 single-parameter tool and no output schema, the description covers the purpose, the prerequisite step, the scope of restoration, and the idempotent outcome. It is fully complete for an agent to select and 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?

With 100% schema description coverage, the schema already explains the parameter 'surface_id' and references list_surfaces. The tool description does not add new semantic information beyond repeating that instruction, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'bring back' and the resource 'surface', specifying that it restores the surface with its sheet and alignment journal. It distinguishes from sibling restore tools by focusing on surfaces and provides a concrete pre-step (list_surfaces with deleted set to 'only').

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 use the tool (to restore a deleted surface) and how to identify the target (using list_surfaces with deleted='only'). It also notes the idempotent behavior ('answers the same') when restoring a surface already in the registry, giving clear expectations.

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 behavior beyond annotations: potential failure due to insufficient credits and no-op for active trackers. No contradiction with annotations (idempotentHint=true matches description).

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, front-loads the core purpose, and covers key behaviors 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 simple tool with one parameter and no output schema, the description fully covers purpose, preconditions, side effects, and idempotency.

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 already describes the parameter adequately. The description adds no extra parameter 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 specifies a clear action ('Start or restart the measurement') on a distinct resource ('tracker') and ties it to a credit balance, differentiating it from siblings like pause_tracker or 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?

Mentions a precondition (insufficient_credits error) and idempotent behavior ('starting an already active tracker changes nothing'), providing clear context for when to call and what to expect, though it doesn't explicitly compare to alternatives.

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

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

Beyond annotations (idempotent, non-destructive), the description discloses batch behavior, error handling (unknown items/languages reject the whole batch and list valid options), partial updates, and the fact that ticking all items has no effect on alignment.

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 is concise, with each sentence contributing necessary information without redundancy. It efficiently covers purpose, usage, behavioral details, and differentiation.

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 all essential aspects: parameters, usage scenario, error behavior, and relationship to sibling tools. It is sufficient for an agent to use the tool correctly 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?

While the schema already covers 100% of parameters, the description adds value by providing examples of item keys (title_tag, llms_txt) and clarifying that the 'ticks' array is a batch operation. This enhances 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 clearly states the verb 'tick' and resource 'checklist items of a surface', and distinguishes itself from the sibling 'mark_surface_aligned' by noting that ticking all items does not mark the surface aligned.

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: use this to record verified items, but to mark the surface aligned use 'mark_surface_aligned' instead. It also implies prerequisites like calling list_surfaces to get item keys.

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 no annotations indicating readOnly, the description clarifies that nothing is charged by the call, the payment happens externally, and balances update automatically after payment. This adds critical behavioral context 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 a single cohesive paragraph of ~150 words, front-loaded with purpose and detailed guidance. While information-dense and clear, a slightly more structured format (e.g., separating parameter guidance) could improve readability, but it remains 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 the tool has no output schema, the description fully covers what is returned (hosted payment link) and side effects (balance update, resumed trackers, data-access window reopening). All necessary contextual information is provided 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?

With 100% schema coverage, the description adds significant meaning: explains the major/minor unit distinction, gives explicit examples (50 means 50.00), and provides decision logic for which parameter to use. This goes well 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?

Description uses strong verb+resource: 'Prepare a top-up of the prepaid credit balance and return the hosted payment link.' This is unique among siblings, as no other tool handles credit top-up or payment links.

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 'amount' (user-named amount) vs 'amount_minor' (computed from cost grid), references get_credits for currency and list_trackers for costs, and warns against currency conversion. Also clarifies the call is not a charge.

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

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

Adds meaningful behavioral context beyond annotations: partial updates, empty field behaviors (label reverts, notes/published_on clear), and that URL change always recomputes source. 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?

Four sentences, each packed with essential information. Front-loads key behavior, no unnecessary words. Highly 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 output schema and good annotations, the description fully covers update behavior, edge cases (empty strings), and alternative tool usage. No gaps identified.

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 has 100% coverage, but description adds crucial guidance: omit label, empty string resets; notes/published_on cleared with empty string; URL recomputes source. This adds significant value 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 description clearly states the verb 'Update' and the resource 'corroboration', and distinguishes from sibling 'archive_corroboration' by noting that editing never takes anything down.

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 mentions when to use 'archive_corroboration' instead (for marking a page as gone). Provides clear context on partial updates and URL recomputation, but does not cover all potential alternatives among 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?

Beyond annotations (idempotentHint, destructiveHint), the description adds critical behavior: partial update 'only fields you send change', and that empty notes clear them. It also reassures that only harmless corrections occur, and clarifies constraint on tool events.

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 essential: core action with behavioral nuance, safety reassurance, and exclusion of tool events. No wasted words, well 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?

Given no output schema, the description adequately covers update behavior, constraints, and safety. Could mention idempotency (already in annotations) or return value, but mostly complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaningful context by explaining the partial update nature and the specific clearing behavior for notes, which goes beyond parameter 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 identifies the tool as editing a manual logbook entry, contrasting with tool events which cannot be edited. This distinguishes it from siblings like create_logbook_entry and delete_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 states that tool events cannot be edited, providing a clear exclusion. However, it does not explicitly tell the agent when to prefer this over creating a new entry or deleting.

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 details idempotency (identical wording records nothing), versioning (next canon version recorded on change), and the behavior of changing language (a normal revision). This goes well beyond the idempotentHint annotation.

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 is front-loaded with purpose. It is slightly long but every sentence provides unique value; 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 tool with 13 parameters and no output schema, the description covers versioning, idempotency, immutability of versions, and the need for user confirmation. It is complete and provides sufficient 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 coverage is 100%, but the description adds essential semantics: omitted fields are kept as is, empty strings clear fields, and language change is a revision. 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 specifies a clear verb and resource ('Revise the brand canon of a project'), and the tool's purpose is distinct from siblings like update_corroboration or update_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 emphasizes that the canon is meant to be STABLE and that revising is a rare, deliberate move requiring user confirmation. It implies when to use (revision) vs. not (creation), though no alternative tools are named explicitly.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable detail about partial update semantics and that empty notes clear them, but does not mention response 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?

Three efficient sentences with no waste. The main purpose is front-loaded, and each sentence adds distinct value (partial update, safety, status alternatives).

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

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

Covers key behavioral aspects for a simple update tool with 3 params. Missing detail about what is returned (e.g., the updated quest), but given low complexity, it is largely sufficient.

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 clear descriptions. The description adds extra semantics about partial updates and empty notes behavior, which is not in the schema and aids correct invocation.

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' with specifics on partial updates, and distinguishes it from sibling tools like complete_quest and dismiss_quest by noting that status changes are handled separately.

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 not to use this tool: 'The status changes through its own moves, complete_quest and dismiss_quest,' guiding the agent to use those tools for status updates.

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. Description adds details on partial update, list replacement, and clear semantics for empty values, enhancing 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?

Two sentences packed with essential information, front-loaded with the core action, then specifics. 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?

With 6 parameters and no output schema, the description covers update behavior, field semantics, and distinguishes from siblings. Lacks mention of response or error cases, but sufficient for basic 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 coverage is 100% with parameter descriptions. Description adds context that fields are optional and only sent ones change, and explains usage for type and label in updates vs. creation.

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 updates the registry sheet of a surface, specifying partial update behavior. It distinguishes from sibling mark_surface_aligned by explicitly stating alignment is done elsewhere.

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: only sent fields change, alignment is moved by another tool, and clarifies behavior for lists and empty strings. Contrasts with create_surface (omitting fields) and mark_surface_aligned.

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 (all hints false), so the description carries full burden. It discloses key behaviors: partial updates, version creation for certain fields, score series continuity across versions, and list replacement. 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 four sentences, each serving a specific purpose. The first sentence front-loads the core partial update semantics. Subsequent sentences add critical behavioral rules without redundancy. 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 13 parameters, no output schema, and minimal annotations, the description covers all essential behaviors: partial updates, version creation, series continuity, list replacement, and response content (new tracker id, version_created). It provides sufficient context for an AI agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, but the tool description adds significant meaning: 'only the fields you send change', 'keywords, analysts and the title apply in place', 'changing prompts/engines/frequency/resolution... creates a new version', and 'a sent list replaces the previous one entirely'. These details are not present in 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 verb 'update' and the resource 'configuration of a tracker'. It distinguishes from sibling tools by focusing on modification, not creation or deletion. The first sentence 'only the fields you send change' immediately clarifies the partial update 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 explicit guidance on when to use the tool by detailing the effects of modifying different fields: keywords/analysts/title apply in place, while changing prompts/engines/frequency/resolution creates a new version. It also explains list replacement behavior, helping agents understand the consequences of updates.

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