Epovest

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

Adds context beyond annotations: all-or-nothing batch behavior, in-place update, series start timing, and error scenarios. No contradiction with annotations.

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

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

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

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

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

No output schema provided, and description only vaguely mentions returned keys ('keyword' or 'keywords') without specifying structure. Missing clear return value details.

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

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

Schema coverage is 100% and description reinforces mutual exclusivity and all-or-nothing, but does not add significant new meaning beyond schema.

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

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

The description clearly states the tool accepts discovered suggestions (domains) to become tracked keywords, distinguishing it from siblings like dismiss_keyword_discovery and list_keyword_discoveries.

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

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

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

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

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

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

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

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

Although the description is longer than average, it is densely packed and front-loaded with the primary purpose. Each subsequent sentence adds necessary detail (examples, idempotency, limits). The structure moves naturally from definition to usage to parameter nuance to operational behavior. No filler or repetition.

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

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

Given the tool's complexity (4 params, nuanced idempotency, behavioral nuance) and the absence of an output schema, the description is remarkably complete. It covers what the check means, how it integrates with tick_surface_checklist, edge cases (restoration, no duplicates, maximum count), and the key parameter decision. No significant information is missing.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. For restates_canon, it explains the key judgment call with a precise question and consequences. It also provides examples for label content and clarifies the default false behavior. This adds value beyond the property descriptions.

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

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

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

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

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

The description provides explicit when-to-use guidance: 'Reach for it whenever the person states something a page must carry that is theirs to decide'. It also gives concrete examples of such situations. However, it does not explicitly mention alternatives (e.g., update_surface_check) or when-not-to-use conditions, which would earn a 5.

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

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

Annotations already indicate it is not read-only but is idempotent and not destructive. The description adds context that nothing is deleted, the line and history stay, and it describes the impact on source presence. This complements the annotations well.

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

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

The description is concise with three sentences front-loading the main action. It could be slightly more structured (e.g., bullets) but is efficient and clear.

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

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

Given the simple action (toggling archived status), the description covers behavior, cautions, and effect on counting. No output schema exists, but the result is implicit. It is complete for this tool's complexity.

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

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

The schema covers both parameters with descriptions. The description reinforces the meaning of archived (true takes down, false puts back, omitted takes down) and provides guidance for corroboration_id to use list_corroborations. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: recording that a page is no longer there or putting it back live. The title also explicitly says 'Take a corroboration down, or put it back live.' This distinguishes it from siblings like create_corroboration or delete_corroboration.

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

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

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

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

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

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

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

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

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

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

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

Given no output schema, description explains side effects, idempotency, default project, and tracker_count in answer. Covers all necessary context for correct invocation.

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

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

Schema coverage is 100% with descriptions. Description adds value: explains default behavior for archived parameter, and that project_id is always UUID from list_projects. Enhances understanding beyond schema.

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

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

The description clearly states the tool files a project away, moves it to the end of list_projects with archived true, and stops offering it when filing a tracker. It distinguishes from siblings by explicitly mentioning archive_tracker and non-cascading behavior.

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

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

Provides explicit when to use (project served its purpose) and when not (trackers continue measuring). Mentions the default project and alternatives like archive_tracker for cascading. Clear usage context.

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

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

The description extensively explains behavioral traits beyond annotations: it moves the tracker, pauses measurement, stops spending, keeps sheet and scores readable, and is idempotent for already archived trackers. Annotations hint at destructive and idempotent, but the description adds concrete context.

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

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

The description is front-loaded with the core action and then elaborates efficiently. Every sentence earns its place, though it could be slightly streamlined without losing value.

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

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

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

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

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

With 100% schema coverage, the schema already documents both parameters. The description reiterates the parameter meanings but does not add new information beyond what the schema provides, so it scores at baseline.

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

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

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

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

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

The description gives explicit context for when to archive (finished campaign, sold brand, ended trial) and mentions reverting with archived false and start_tracker. However, it does not explicitly compare with sibling tools like archive_project or provide when-not-to-use guidance.

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

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

Discloses idempotency, effect on dismissed quests, state changes (sets state and closing date), and lifecycle (readable in closed history, reopenable). No contradiction with annotations.

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

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

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

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

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

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

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

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

Schema provides full description for quest_id, and tool description does not add extra information beyond that. Baseline 3 is appropriate.

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

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

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

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

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

Provides clear context: use when the move happened. Mentions idempotency and safe retry. Also covers edge case of dismissed quests. Lacks explicit 'when not to use' but still strong.

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

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

The description adds context beyond annotations: it explains that the message lands in support threads visible to members and that a human will answer. Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature, but the description clarifies the human response process and thread behavior.

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

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

The description is concise with two sentences that cover purpose, usage, and reply behavior. Information is front-loaded and every sentence adds value without redundancy.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description goes beyond the annotations by detailing data preservation (nothing retyped, publication date copied into notes), type derivation rules, idempotency (replaying finds the same line), and non-destructive nature (sheet intact). These behavioral traits are not covered by the existing annotations and are critical for safe use.

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 where every sentence contributes meaningful information—usage scenarios, data transformations, reversibility, and user confirmation. There is no redundancy or filler.

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

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

The operation is complex (reverse move, data transformations, idempotency, user confirmation), and the description covers all these aspects thoroughly. No output schema exists, but the description sufficiently explains what happens without needing to document return values.

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

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

The schema already fully describes the single parameter (corroboration_id) with guidance to call list_corroborations. The description adds no further parameter-specific details, so the baseline of 3 applies.

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

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

The description clearly states the action ('Move the page to the surface registry') and explains the specific condition under which it applies (customer has final say). It distinguishes from the reverse sibling tool by naming it explicitly, making the purpose unambiguous.

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

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

The description provides concrete scenarios for use (customer's own profile/listing recorded on wrong side, or source becoming a reliable channel) and warns to confirm with the user first. It also mentions the reverse move as an alternative, giving clear context for when this tool is appropriate.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly states the action: 'Move a surface to the corroboration registry' and explains the effect clearly. It differentiates this tool from its reverse sibling (convert_corroboration_to_surface), making the purpose distinct.

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

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

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

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

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

Annotations provide no safety signals (all false), so the description must disclose behavior. It does so by stating the scan is created as a DRAFT with no charge, that derived questions are returned for review, and that the engine is one per scan with ChatGPT as default. This adds significant context beyond the annotations, though it does not cover failure modes or detailed persistence.

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

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

The description is longer than a simple two-sentence blurb but every sentence adds value. It is well-structured, covering purpose, draft behavior, parameter usage, and engine defaults. There is no filler or repetition, though it could be more scannable with bullet points.

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

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

With 9 parameters, no output schema, and no annotation hints, the description covers the essential flow: draft creation, no charge, questions returned, parameter meanings, and engine default. It is reasonably complete, although it doesn't describe the exact response format or edge cases like invalid websites.

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

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

The schema covers 100% of parameters, but the description adds meaningful semantics: website is the whole domain to distinguish same-name companies, category and usage shape the questions, language is for the question wording, country for the market, and leaving country out means global. 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's purpose: 'Prepare a competitor scan on a basket of up to 5 companies of the same market.' It distinguishes itself from sibling tools by explicitly mentioning the draft phase and referencing start_competitor_scan as the next step after arming. The verb 'prepare' is specific to creating a draft, not starting or listing scans.

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: before arming with start_competitor_scan, and it explains that a second engine requires a second scan, implying one scan per engine. It does not explicitly list alternatives like update_competitor_scan, but the workflow is clear enough for an agent to select this tool for creating a draft scan.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false, which is thin. The description adds essential behavioral context: the agent must actually read the page and confirm with the user, and the page is a statement of fact. It also documents refusal behaviors. This goes beyond annotations without contradicting them.

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

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

The description is longer than average but every sentence earns its place: it defines the resource, explains the URL-first rule, mandates a human check, gives the surface exclusion test, and lists error refusals. It is front-loaded with the core purpose before branching into usage 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?

The tool is conceptually nuanced (corroboration vs surface), and the description handles this thoroughly with the customer-control test and refusal slugs. It doesn't describe the success return payload, but no output schema exists and for a create operation this is a minor omission given the rich usage and error guidance.

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

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

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds context about URL-first derivation and label omission, but this largely echoes the schema. No extra parameter-level semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Record a page about the brand where someone else has the final say.' It immediately distinguishes from the sibling tool create_surface using the control test ('if the customer changes the page, does the change stay?'), making the tool's 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 when to use this tool versus create_surface ('A page the customer controls ... belongs to Surfaces instead: use create_surface'), provides a decision test, and lists three refusal slugs (unplaceable_url, own_domain, duplicate) so the agent knows likely failure modes and how to respond.

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, it discloses that the entry becomes an annotation on tracker citation curves, that idempotence is keyed on project_id + label + occurred_at, and that multi-language labels or quests produce distinct entries. It also explains the normal-case date semantics. No contradiction with the annotations.

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

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

The definition is long but dense; each sentence adds a distinct fact such as date semantics, curve annotation, idempotence, duplicate labels, and quest routing. The core purpose is front-loaded, and there is no filler.

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

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

For a create tool with six parameters and no output schema, this is complete: all parameter states are covered, retry behavior is specified, and project/quest discovery is already provided in the schema. An agent can correctly select and invoke it 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?

There is 100% schema coverage, but the description adds semantic depth: it pinpoints the idempotence key, clarifies occurred_at as action time rather than recording time, and explains how label and quest_id affect duplication. Notes and category remain schema-covered but not enriched, which is sufficient given the schema already documents them.

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

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

The description names the action (record), the object (logbook entry of a project), and immediately clarifies the key semantic: what was done and when. The verb and object separate it from sibling tools like get_logbook, update_logbook_entry, or delete_logbook_entry even without explicit sibling comparison.

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

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

It gives explicit conditions: pass quest_id when the action moves a quest forward, omit/null quest_id for project-only entries, and use occurred_at for the action date rather than the recording time. It also tells the agent that retries are safe because of idempotence. It doesn't name an alternative tool for editing or deleting, but the context is clear enough for selection.

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

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

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

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

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

The description is a dense paragraph but every sentence provides necessary context: purpose, canon rules, filing behavior, and duplicate handling. It's front-loaded with the main purpose and avoids repetition.

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

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

For a creation tool with no output schema, the description fully explains the key behaviors: what is created, what is not, how to use the returned id, and how duplicates are handled. The schema covers parameter details, so the description only needs to cover higher-level semantics, which it does thoroughly.

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

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

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

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

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

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

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

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

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

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

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

The description goes well beyond the idempotentHint annotation by unpacking the exact semantics: a retry does not fail or duplicate, it returns the quest already in the file, and the idempotency is scoped to project + title while open. It also discloses the closed-quest edge case and the storage model (quests live in the project's file). No contradiction with the annotations; readOnly=false and idempotent=true are 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?

Three sentences around 110 words, purpose first, followed by the idempotency behavior and the closed-quest exception. The embedded example makes the concept concrete without adding length, and 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 flat 3-parameter create with 100% schema coverage and annotations covering safety and idempotency, the description is nearly complete: it even sketches the return value (the quest already in the file). The only gap is explicit when-not-to-use guidance against quest-lifecycle siblings, which would make tool selection fully unambiguous.

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

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

Schema description coverage is 100%, so the schema alone documents notes, title, and project_id. The description adds cross-parameter meaning: title is not just display text but the idempotency key alongside project_id, and notes carry the context and links that keep the work resumable. That is genuine added value, not mere repetition.

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

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

States the verb 'add' and the resource (a quest into a project's file), then defines what a quest is in domain terms: 'a next move the customer decided, kept where the work resumes', with a concrete example. This clearly distinguishes it from the many other create_* siblings that target different resources such as projects, corroborations, or surfaces.

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 when adding a quest is appropriate (when the customer decided a next move) and gives precise retry guidance: calling again while the quest is open is safe and returns the existing quest, while a closed quest with the same title starts fresh history. It does not, however, explicitly route among the quest-lifecycle siblings such as update_quest, complete_quest, dismiss_quest, or reopen_quest.

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

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

Annotations are all false, so the description carries the burden of explaining side effects. It discloses that the surface is created as 'never_aligned' and that alignment derives from checklist verifications, never declared. This adds meaningful behavioral context beyond the annotations, though it does not cover error conditions or permissions.

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 earns its place: definition, decision test, URL-first rule, derivation logic, and lifecycle state. Though longer than a typical tool description, it is dense with actionable guidance and no 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?

Given the tool's complexity (6 params, no output schema, related workflows), the description covers purpose, usage, and state transitions well. It lacks explicit mention of the return value/response, but the operational ambiguity is low because the focus is on creation and later alignment.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds crucial semantics: URL is the only required input, type and label are derived (pass only to correct), and the derivation rules are explained. This goes beyond the schema's per-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 states the tool's purpose: 'Register a surface of a project' and provides a precise definition of a surface. It explicitly distinguishes itself from create_corroboration with a decision rule, making it unmistakably different from 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 gives explicit when-to-use guidance via the customer-change test and even names the alternative tool (create_corroboration). It also instructs when to omit type/label (URL-first) and when to pass them only to correct derivations, plus points to the next step (tick_surface_checklist).

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

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

With all annotations false, the description carries the full disclosure burden and delivers: the draft state ('measures nothing yet'), the credit-balance dependency, validation parity with the app configurator, and the behavioral difference between omitted next_survey_at and an explicitly scheduled date. It does not contradict the annotations (readOnlyHint=false aligns with a create operation). Minor gaps remain, such as not stating that each call produces a distinct tracker, though idempotentHint=false already signals this.

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

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

Five sentences, all dense and purposeful: purpose, launch workflow, validation expectation, and two parameter-behavior clarifications. The critical draft-state fact is front-loaded. Minor prose roughness ('Omitted, next_survey_at means...') and slight redundancy between the next_survey_at and frequency guidance keep it from a 5.

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

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

For a 12-parameter create tool with no output schema, the description covers the trickiest behavioral semantics (draft state, launch linkage, on_demand mode, omission behavior) while the 100%-covered schema handles the per-parameter detail like custom_prompt dependencies and pricing. The main absence is any mention of what the tool returns on success (e.g., a tracker ID), which matters more here because no output schema exists. Everything required to invoke it correctly is nonetheless present.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds it by adding cross-parameter and workflow semantics the per-parameter schema entries lack: what omitted next_survey_at means at start_tracker time, and how frequency=on_demand interacts with start_tracker and survey_now. It explains the orchestration between parameters rather than restating their individual meanings.

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

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

States a specific verb and resource ('Create a tracker in draft') and immediately distinguishes itself from the launch action by naming start_tracker explicitly. The draft-state framing is the key differentiator: this tool creates but does not run, which separates it cleanly from the many create_* siblings (create_project, create_surface, create_quest) and from start_tracker/survey_now.

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 workflow is explicit: create in draft, then call start_tracker to launch against the prepaid credit balance, and use survey_now for subsequent on-demand readings. The on_demand single-reading scenario is spelled out concretely. It stops short of a full when-not-to-use list (e.g., no explicit contrast with update_tracker for later edits), so it earns 4 rather than 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description explicitly says 'Only do it when the user asked for it: it is their logbook,' which guides appropriate use. It also mentions the alternative (restore_logbook_entry) and clarifies that tool events are unaffected, preventing misuse.

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

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

Annotations already provide idempotentHint=true and destructiveHint=true. The description adds that the sheet and alignment journal are kept, and restore_surface brings them back, reinforcing idempotency and clarifying non-destructive aspects.

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

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

The description is brief (three sentences), front-loaded with the main action, and every sentence is informative. No redundant or extraneous text.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, idempotency, recovery, and side effects. Annotations complement but description adds necessary behavioral context.

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

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

Schema coverage is 100% and provides adequate description for surface_id (UUID format, call list_surfaces). The tool description does not add further parameter details, so baseline score of 3 applies.

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

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

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

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

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

The description gives explicit use cases: 'for a page that is gone (account closed, listing removed) or for a line that had no place there.' It also mentions idempotency and recovery via restore_surface, though it lacks explicit when-not-to-use guidance.

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

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

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

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

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

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

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

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

Given the tool's moderate complexity (2 params, no output schema) and strong annotations, the description fully covers what happens, when to use, the soft-delete behavior, recovery path, and idempotence. Agents have enough to decide, invoke, and anticipate side effects without additional context.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents surface_id and check sufficiently. The description adds conceptual context by referencing 'check of your own' and pointing to list_surfaces/add_surface_check, but doesn't introduce new parameter syntax or format details beyond schema, hence baseline 3.

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

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

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

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

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

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

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses that nothing is created or deleted, and the page will never be proposed again. It also clarifies how mis-filed pages can be moved, reducing decision anxiety. 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 moderately long but every sentence earns its place by clarifying usage, behavior, or alternatives. It is front-loaded with the primary action and then expands logically. Could be slightly tightened but no wasted words.

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

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

For a simple dismissal tool, the description fully covers what it does, when to use it, what it doesn't do, and how to handle related scenarios (accepting, converting). An output schema is absent, but the description makes the tool's effect clear enough without needing return-value details.

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

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

The schema already covers both parameters with descriptions (100% coverage), but the description adds practical sourcing guidance: url should be exactly as list_corroboration_candidates provides it, and project_id is a UUID from list_projects. This extra context elevates beyond 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 tool refutes a suggested page, permanently removing it from future proposals for the project. It gives specific usage criteria and distinguishes it from accepting by pointing to create_corroboration and create_surface as opposite moves.

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

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

Provides explicit when-to-use conditions (excerpt matched something else or page not worth recording) and when-not-to-use with explicit alternatives (create_corroboration, create_surface, convert_corroboration_to_surface, convert_surface_to_corroboration). This is exemplary guidance.

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

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

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

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

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

The description is a single dense paragraph that front-loads the main purpose and covers all behavioral details without unnecessary words. Every sentence adds value.

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

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

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

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

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

Input schema has 100% coverage; domain/domains/tracker_id are well-described. The description adds no new parameter-level meaning beyond what the schema provides, so baseline score applies.

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

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

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

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

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

The description explains the effect of dismissal (never proposed again) and the all-or-nothing batch behavior, but does not explicitly state when to use this tool versus alternatives like accept_keyword_discovery. Usage context is implied rather than explicit.

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

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

The description adds value beyond annotations: explains idempotency (safe retry), side effects (state, closing date), and that the quest remains readable (non-destructive). No contradictions with annotations.

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

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

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

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

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

For a simple mutation tool with one parameter and no output schema, the description fully covers behavior, effects, and relationship to reopen_quest. Complete and self-contained.

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

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

Schema coverage is 100% with a clear parameter description. The tool description does not need to add more parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool sets a quest aside when the customer decides the move is off. It distinguishes from siblings like reopen_quest and complete_quest by specifying the action and effects.

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

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

The description provides usage context (when customer decides move is off) and mentions safe retry and reopen_quest for reversal. However, it does not explicitly contrast with other quest-related tools like complete_quest.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value beyond these by specifying exactly what data is returned (all account settings) and clarifying the role of 'member' (the person the language and time zone belong to). It also notes the read is a snapshot ('as it stands'), which is useful context for using the result before an update.

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 list of settings and then the usage instruction. Every sentence earns its place: the first defines the resource, the second provides the workflow guidance. No wasted words or padding.

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

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

For a no-parameter, read-only tool with an output schema absent, the description fully covers what an agent needs: what the tool returns (all settings), why it exists (to read before updating), and how it relates to sibling update_account_settings. Annotations cover safety, so nothing critical is missing.

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

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

The tool has zero parameters, so the schema provides no parameter details. The description does not need to add parameter meaning, but it does clarify what the output will contain, which is relevant context. Since there are no parameters, the baseline of 4 applies, and the description helps make the tool's purpose and result clear without parameter 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 states the verb 'Read' and the resource 'account settings', then enumerates the specific fields (legal name, billing country, postal address, VAT number, language, time zone, member). It clearly distinguishes itself from the sibling update_account_settings by framing itself as the read step before an update, so an agent can easily tell them apart.

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 'Read it before update_account_settings' and explains why: 'the answer gives every setting as it stands, so you change the one the user named and leave the others alone.' This provides clear when-to-use guidance and directly contrasts with the sibling tool, leaving no ambiguity about the intended workflow.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds rich behavioral context: return structure (canon keys, canon_version, history newest-first with author/date/changes), raw value formats (perks as ordered list, language short code), and the null/empty behavior for unposted canons. It goes well beyond what annotations provide.

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

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

The description is front-loaded with the core purpose, then progressively layers structure and usage. Every sentence carries unique information—no fluff. It is longer than average but each clause earns its place by explaining return fields or the re-propagation workflow.

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

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

There is no output schema, but the description thoroughly explains what the agent will receive: the canon object with specific keys, canon_version, history array with author/date/changes, and raw value semantics. It also covers the edge case. For a read-only tool with strong annotations, nothing important is missing.

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

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

The schema covers the only parameter (project_id) with a description and format, and points to list_projects. The description does not add anything about the parameter beyond that, which is acceptable given 100% schema coverage. Baseline 3 is appropriate.

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

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

The description opens with a clear verb ('Read') and resource ('the canon of a project and its history'), and immediately distinguishes it from get_logbook by explaining that this returns the canon's history and is used for re-propagation. This makes the tool's unique purpose unambiguous even among 50+ 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?

It explicitly names when to use it: 'Reach for it to RE-PROPAGATE a revision' and explains the relationship to get_logbook (which says a canon moved to a version and which keys it touched). It also covers the edge case when canon is not posted. This gives the agent concrete decision rules.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing specific behaviors: the list ACCUMULATES over every check, is deduplicated by URL, and seen_in_checks counts checks not citations. It also explains the semantics of each field (subjects, reach, client_present, controlled, rivals) and gives actionable next steps. This is rich behavioral context that annotations alone do not provide.

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

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

The description is a long, dense paragraph, but every sentence carries meaning—explaining accumulation, deduplication, field definitions, reach types, and actions. It is front-loaded with the core object description and weaves in necessary nuances without fluff. It is wordy but efficient for the complexity of the returned data, so it earns a 4 rather than a 5.

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 rich output with many fields and no output schema provided, the description does a strong job of explaining all key concepts: subjects, reach categories, client_present, seen_in_checks, controlled, and rivals. It also explains how to act on a place. However, some phrases like 'the number that carries the tool' are ambiguous, and it doesn't address pagination or possible empty results. Overall, it is nearly complete but not fully unambiguous.

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 competitor_scan_id is fully described in the schema with 'The UUID of the competitor scan: call list_competitor_scans to find it.' Since schema coverage is 100% and the description does not add any additional parameter-specific details, the baseline score of 3 is appropriate. The description focuses on the response structure rather than the parameter, which is acceptable given the schema already covers it.

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

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

The title 'Read a competitor scan' and the description clearly state the action and resource. It distinguishes itself from sibling tools like list_competitor_scans, update_competitor_scan, and create_competitor_scan by focusing on retrieving a single scan's detailed place list. The description explicitly explains what the tool returns and even cross-references create_quest for acting on places, leaving no ambiguity about its function.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies that you use it to inspect the places of a specific scan, and mentions that list_competitor_scans is a way to find the scan ID, but it lacks direct exclusions like 'use list_competitor_scans to get an overview, use this for detailed place data.' The guidance is present but implicit, not explicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes beyond by explaining the response structure (fields like monthly_estimate_minor, suggested_topups, min_topup_minor) and the edge case when the account consumes nothing yet. Since there is no output schema, this disclosure is essential and well done.

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 dense but every sentence adds value: core purpose is front-loaded, followed by usage timing and then detailed output semantics. No fluff; the length is justified because it compensates for the lack of an output schema.

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

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

Given 0 parameters and no output schema, the description fully covers what the tool returns, how to interpret each field, and the special case for a new account. Nothing an agent needs to call and use this tool correctly is missing.

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

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

Tool has zero parameters, so schema coverage is trivially 100%. Per rubric, 0 params earns a baseline of 4; no parameter explanations needed, and the description correctly focuses on output interpretation instead.

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 verb 'get' and the resource 'prepaid credit balance', and specifies exactly what it returns (available credits, reserved amounts, reservations). It also gives a precise use case ('Read it before starting a tracker'), which helps distinguish it from other read tools in the sibling list like get_usage or get_account_settings.

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: 'before starting a tracker' and 'when a call fails with insufficient_credits'. It does not mention when not to use or name alternatives, but for a read-only balance check, the provided guidance is sufficient and practical.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context beyond that: it explains the output structure (derived vs free), the meaning of 'canon' and 'surface' sources, and how these addresses relate to the reading pass report. 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 detailed but each sentence contributes value: it explains output types, definitions, usage guidance, and the relationship to reading passes. It could be slightly trimmed without losing meaning, but it is well-structured and front-loaded with the main output.

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 get tool with one parameter and no output schema, the description fully covers what the agent needs: what the two lists contain, how derived differs from free, and why this matters before setting targets. Nothing essential is missing.

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

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

The only parameter project_id is fully described in the schema with a hint to call list_projects. The description does not add additional meaning about the parameter itself, so a baseline of 3 is appropriate given 100% schema coverage.

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

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

The title and description clearly state the tool retrieves link target addresses for a brand. It explains the two output lists (derived and free), distinguishing this read operation from sibling set_link_targets, and the verb 'get' plus resource 'link_targets' is specific.

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

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

Explicitly directs the agent to read this before setting anything ('Read it before setting anything'), and explains that derived addresses do not need to be added. This provides clear when-to-use guidance and implies the workflow with set_link_targets.

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 idempotentHint=true, but the description adds rich behavioral context: the composition of items from two sources, the structure of canon_version (including 'changed' keys), the semantics of occurred_at vs published_on, and the fact that moves also land as annotations on citation curves. It even explains the deleted='only' trash behavior. These details go far beyond what annotations provide.

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

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

The description is long and dense, packing many details into a single paragraph. While every sentence adds value and there is no redundancy, the wall of text could be more approachable with bullet points or explicit separation of concepts. It's efficient but slightly overwhelming; still, it earns its length given the complexity.

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

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

With no output schema, the description compensates by describing the return items: it explains the two source types, the canon_version item's fields, the corroboration item's date semantics, and the behavior of deleted. It also covers all filtering options and even directs to list_projects for project_id. An agent can call this correctly with no further info.

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

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

The schema already covers all parameters at 100%, but the description adds meaning beyond the schema: it clarifies that tool events carry no category or quest, explains the difference between source values, and describes the behavior of quest_id as 'THIS is the dated trail of one quest'. It effectively bridges the gap between raw schema enums and real-world usage.

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 reads the logbook of a project, newest first, and specifies the two sources (tool and manual). It distinguishes itself from the many list_* siblings by focusing on the logbook as a composite record. The purpose is specific and unambiguous.

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

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

The description provides direct usage guidance: 'read the logbook to tell what was done when the curves moved' and how to filter via quest_id or deleted. It even references related tools (list_quests, list_projects) for finding IDs. It also explains that tool events never match category/quest filters, which helps decide when to use filters. There's no ambiguous 'when not' because this is the only logbook read tool.

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

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

Annotations already declare the tool safe (readOnly, idempotent, non-destructive), and the description adds significant behavioral context beyond that: pagination behavior, ordering (newest surveys first), the exact fields returned (cited sources, keyword mentions, uncited_sources, searched), and performance guidance ('heavy, ask for it only when needed') for include_raw. No contradictions with annotations.

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

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

Three concise sentences front-load the core purpose, then dive into response fields and a parameter caveat. Every word earns its place; no fluff or redundancy. The structure is ideal for quick agent parsing.

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

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

The description covers the main aspects an agent needs: scope, ordering, pagination, response fields, and the heavy include_raw flag. With an output schema absent, it adequately explains return values. Minor gaps like error handling or rate limits are not critical for a read-only, idempotent tool with well-documented schema parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra guidance on include_raw ('heavy, ask for it only when needed') which affects parameter usage, and clarifies pagination/ordering that relates to page/per_page and survey filtering. This is a slight improvement over bare 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 identifies what the tool returns: 'raw answers of ONE AI engine for a tracker' with a specific scope (single engine), ordering (newest surveys first), and pagination. It also lists the fields carried (cited sources, keyword mentions, uncited_sources, searched), making the purpose unambiguous and distinct from sibling tools that likely aggregate or provide different views.

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 or when not to use it. It implies usage via the specific phrasing ('raw answers of ONE AI engine'), which guides an agent to pick this when per-engine raw data is needed, but it lacks a clear exclusion clause or mention of alternative tools like get_results or get_source.

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 idempotentHint=true, so the safe read behavior is covered. The description adds valuable behavioral detail: the variable fields per analyst (citation_rate and weighted_score, share_of_voice, or sentiment counts) and the chronological order of rows. This goes beyond the annotations and helps the agent predict the response shape.

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 redundancy, front-loaded with the core purpose. The description is tight and informative without unnecessary flourishes. Every clause carries meaning.

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

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

For a read-only query tool with no output schema, the description covers the row structure, dimensions, ordering, and field variations by analyst. It does not mention pagination or limits, but for an analytical series tool that may be acceptable. The missing usage guidance slightly reduces completeness, but overall the tool is well-specified for its complexity.

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

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

Schema description coverage is 100%, so each parameter has a description. The tool description does not repeat parameter details but the schema's analyst field already explains the custom_prompt exclusion. The description adds no further semantic value beyond the schema; baseline 3 is appropriate since 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 what the tool returns: 'The score series of a tracker' with explicit row dimensions (analyst, keyword, engine, tracker version, survey period) and chronological ordering. It distinguishes the data granularity from a simple list, though it doesn't name alternative tools. The title reinforces the 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?

No guidance is given on when to use this tool versus siblings like get_responses or list_trackers. The context implies it's for analytical series but there's no explicit recommendation or exclusion. The only related hint is in the schema for tracker_id ('call list_trackers to find it'), which helps locate the required parameter but not when to choose this tool.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the description need not repeat that. It adds context beyond the annotations by explaining the result content ('domain and AI Authority') and implying this is an unfiltered/unranked fetch. 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?

Two tightly written sentences with zero redundancy. The core purpose is front-loaded, and the routing to list_sources comes second as a helpful supplement. 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?

For a single-parameter read tool with annotations covering safety and idempotency, the description is complete: it states what is returned, how to obtain the id, and when to use the sibling tool. No output schema exists, but the description gives sufficient expectation of the result. No missing critical context.

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

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

Schema description already covers the sole parameter (source_id) with format and guidance to call list_sources. The tool description repeats this guidance without adding new semantic detail. With 100% schema coverage, the baseline of 3 is appropriate; the description does not degrade or enhance the parameter understanding.

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

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

The description states a specific verb ('read'), a specific resource ('one entry of the Atlas'), and the exact return content ('the domain and its AI Authority on each AI'). It also distinguishes itself from list_sources by noting the filtering/ranking alternative, making the tool's identity clear.

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

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

Explicitly instructs the agent to call list_sources to find a source id or to read filtered/ranked entries, thereby drawing a clear line between this tool and its sibling. The agent knows exactly when to use this tool (single entry by id) and when to use 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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds context about the content (messages and support answers) and the intended workflow, but does not disclose additional behaviors like return format or rate limits. With annotations carrying the safety burden, this is adequate but not rich.

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 short, front-loaded sentences. The first states what the tool returns, and the second gives the usage context. No wasted words; every sentence contributes to the agent's understanding.

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

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

For a simple read tool with one parameter and no output schema, the description tells the agent what it returns, when to use it, and indirectly how to get the parameter (via schema). It is complete enough for the agent to invoke it correctly, though it doesn't elaborate on the exact response structure.

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 the parameter description explicitly stating 'The UUID of the support thread: call list_support_threads to find it.' The main description adds no additional information about the parameter, so it does not go beyond what the schema already provides. 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 states the tool returns 'One support thread with its messages, including the answers of the support team,' which clearly identifies the resource and action. It also ties to a specific workflow with 'after contact_support,' distinguishing it from list_support_threads which lists threads rather than reading a single one.

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

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

The description explicitly says to use it 'after contact_support to relay the answer to the user,' providing a clear trigger and purpose. It does not explicitly mention alternatives or when not to use it, but the phrase 'after contact_support' implies a sequencing that effectively guides usage.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds substantial behavioral detail: pagination clamping, the on_demand semantics, cost-line breakdown, created_at precision, and the forecast/actual distinction. It fully discloses the operation's behavior without contradicting annotations.

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

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

The description is long but highly structured, with numbered sections for the three answers, then cost lines, fields, and pagination. It front-loads the core purpose and each sentence carries informative weight given the tool's complexity. 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?

With no output schema, the description must explain return values, and it does so exhaustively: field meanings, forecast vs actual, cost-line breakdown, pagination limits, on_demand flags, and timestamp format. It also covers filtering options and points to get_credits for remaining spend. Nothing needed for correct invocation is omitted.

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 50% coverage (type and month have descriptions). The description enriches these by explaining type values ('in' for top-ups, 'out' for spend) and month format, and adds meaning to page (clamping) that the schema lacks. However, per_page is left undefined in text, relying on its numeric nature, so it doesn't fully compensate for all parameters.

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

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

The description states the tool returns account spend data in three distinct forms (this-month forecast, per-month actual, over-window actual) and clearly differentiates them, with a specific verb and resource. It also names a sibling (get_credits) to avoid confusion, making the purpose unambiguous.

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

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

Explicitly instructs when to report forecast vs actual, warns against mixing them, explains the window is never monthly, and recommends separating on_demand sources. It also points to get_credits as the alternative for remaining spend, giving 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context: ordering (newest first), status meanings (draft, measuring, ready, failed) and what each implies, rescan_cadence semantics, and the explicit lack of places in the list. This goes beyond annotations without contradicting them.

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

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

The description is a bit lengthy but well-structured: core purpose first, then conceptual detail, status enumerations, and a pointer to the sibling tool. Each sentence adds value and no information is wasted. It is appropriately sized for the tool's complexity, though slightly dense.

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

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

For a list tool with one optional parameter and no output schema, the description covers what the list contains (statuses, rescan_cadence, order), clarifies that places are not included and how to obtain them, and gives status meanings. This is sufficient for an agent to call the tool and interpret results without needing an output 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 description coverage is 100%; the parameter project_id is fully described in the schema (including that omitting it means every project). The description only repeats 'Scope to one project with project_id' and adds no 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 lists the competitor scans of an account, newest first, and explains what a competitor scan is (a basket of companies for a market/engine). It explicitly distinguishes itself from get_competitor_scan by noting the list does not include the places, which the 'fiche' carries. This gives a precise verb+resource and differentiates from a sibling tool.

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

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

Provides explicit usage guidance: 'Without the list of places... call get_competitor_scan for one scan' directly tells the agent when to use the alternative. Also instructs to scope with project_id, and omitting it targets every project. Clear when-to-use and when-to-use-another conditions are present.

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, idempotentHint, and destructiveHint false, and the description aligns. It adds valuable behavioral context: the list is recomputed on every read from raw payloads, surveys_scanned counts the read surveys, and it explains the matching logic (matched_by: website vs name), the three suggested values, and the page_check statuses (blocked, unreachable, no_page, unreadable) with their implications. 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 long (about 300 words) but each sentence carries dense, necessary information. It front-loads the core purpose, then explains candidate types, page_check details, and actions. While it could be structured more with bullet points, there is minimal redundancy and every part adds value.

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

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

Given the tool's complexity, the description is remarkably complete. It covers dynamic recomputation, field meanings (matched_by, suggested, page_check, excerpt, checked_at), the three suggested registry values with logic, the 'ask' decision procedure, and fallbacks when page reading fails. No output schema exists, so the description carries the burden, and it does so thoroughly.

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

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

The schema fully documents the single parameter (project_id) with description 'UUID of the project: call list_projects to find it.' The description doesn't add extra meaning beyond the schema, and schema coverage is 100%. Baseline 3 applies; the description does not need to compensate.

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

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

The description clearly states the tool lists pages where search engines showed the brand ('MENTIONS a search engine has shown the brand in'), and distinguishes itself from sibling tools by noting it returns suggestions only, not filings, and that pages already in registries are excluded. This differentiates it clearly from create_/dismiss_ tools.

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

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

The description is explicit about when to use it (to get candidate pages) and what to do with results: file via create_corroboration or create_surface, refuse via dismiss_corroboration_candidate. It provides detailed decision rules for 'ask' candidates (test with the user) and warns against guessing from host, giving concrete examples. It also explains the page_check outcomes and that the excerpt stays as proof in failure cases.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds value by specifying the ordering (live first, archived later), clarifying that the data is customer-declared (not verified), and explaining the conceptual split versus Surfaces. It does not contradict annotations and provides context beyond the structured hints, though it could mention pagination or error conditions.

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 includes tangential domain explanations about the Surfaces registry, control split, and logbook behavior. The core purpose is in the first sentence, but subsequent sentences add conceptual background that could be moved elsewhere or trimmed. It is not front-loaded and contains several non-essential details for an agent to call the tool correctly.

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 a simple read-only list with one parameter and no output schema, the description adequately explains what is returned (fields), the ordering, and how it differs from candidates. It lacks explicit mention of response format (e.g., JSON array) but that is often implied. Overall, an agent can decide and invoke correctly without missing critical context.

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

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

The schema covers the only parameter (project_id) with a clear description and pointer to list_projects. The tool description does not add any further meaning about the parameter beyond what the schema already provides, 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 it lists the corroborations recorded for a project, specifying exactly what each entry includes (address, source domain, publication date, notes). It explicitly differentiates itself from sibling list_corroboration_candidates by noting that candidates are proposed pages the engines already showed, while this returns the customer-declared registry.

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 contrasts corroborations with the twin registry of Surfaces, explaining the split is about control, not authorship or payment. It also mentions list_corroboration_candidates as the alternative for proposed pages, giving clear context on when to use this tool vs. that one. However, it does not explicitly state 'use this when you need the confirmed list' or list exclusion criteria beyond the contrast.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable behavioral context: the list is recomputed on every read, the dismissed set is carried and disjoint, and that decisions rest with the user. This exceeds the shallow safety info in annotations, though it doesn't detail the exact return format or pagination.

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 thoughtfully structured: it opens with the core purpose, then explains the recomputation, the dismissed list, and the disjointness, and ends with user guidance. While longer than two sentences, each sentence carries distinct information and no fluff, and the most important fact is front-loaded.

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

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

The description is comprehensive for a tool with no output schema. It explains what the response contains (suggestions and dismissed list), their relationship (disjoint), how the data is computed, and the appropriate action (relay to user). It also gives the restoration path, ensuring an agent can act 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?

With only one required parameter and 100% schema description coverage, the schema already documents tracker_id as the UUID and directs to list_trackers. The description adds no additional parameter semantics; it operates at baseline because the schema covers 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?

The description clearly states the tool lists keyword suggestions discovered on a tracker, specifying the resource (tracker) and the precise nature of the suggestions (domains engines cite repeatedly and that no tracked keyword covers). It distinguishes from sibling tools like restore_keyword_discovery and dismiss_keyword_discovery by explicitly defining the discovered set and its disjointness from dismissed domains.

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

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

The description gives explicit usage guidance: present the suggestions to the user and leave the tracking decision to them. It also indicates when to use restoration (if the user changes their mind) and clarifies that dismissed domains are excluded, implicitly steering the agent to this tool for presenting viable suggestions rather than restore operations.

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

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

Annotations already declare readOnly and idempotent hints, so the description adds value by detailing the ordering (in-use first, then archived) and the virtual Default project for trackers without a project. It also describes the fields returned (id, name, canon_version, archived flag, tracker count), which goes 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 concise, using two sentences to convey the purpose, return fields, and ordering. It is informative yet not overly verbose, though the second sentence packs several details into one sentence. It is 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?

With no output schema, the description adequately describes the return structure (fields and ordering) and even mentions the Default project special case. For a simple read-only list with no parameters, everything an agent needs to use it correctly is present.

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 schema is complete at 100% coverage. The description correctly focuses on the operation rather than parameters, and with zero parameters there is nothing to explain. The baseline of 4 for 0 params 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 lists account projects and defines what a project is (folders for trackers). It explains the purpose and even clarifies the organization-only nature, distinguishing it from other list tools by focusing on projects specifically. The verb and resource are clear.

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

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

The description does not explicitly state when to use this tool versus alternatives like list_trackers or list_surfaces. It implies usage by naming the resource, but there is no direct comparison or exclusion provided. The context is clear but the guidance is only implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the bar is lower. The description adds substantial behavior context: default ordering (newest first), how status filters work, the `pending` concept, journal_entries and last_entry_at fields, and the interpretation of empty results. No contradiction with annotations and enriches the agent's understanding of behavior.

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

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

The description is a dense, unstructured paragraph with multiple tangents about pending files, logbook entries, and related tools. While every sentence adds value, the length and lack of formatting (bullets, sections) make it hard to parse quickly. It is front-loaded with purpose but then becomes overly verbose, harming usability.

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 (status modes, scoping, pending sub-resources, logbook fields), the description is thorough and covers all relevant aspects an agent needs to call it correctly. It explains response contents (journal_entries, last_entry_at) and even the meaning of an empty file. No obvious gaps.

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

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

Schema coverage is 100%, providing baseline of 3. The description adds meaning beyond schemas: status default ('open by default'), the effect of status values (done/dismissed read closed history), and the implication of omitting project_id (covers every active project). This goes beyond simple field definitions.

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: 'Lists the quests of the account' with a specific verb and resource. It also distinguishes itself from sibling tools by mentioning alternatives (list_surfaces, list_keyword_discoveries, list_corroboration_candidates) and explaining how they relate. No ambiguity about what the tool does.

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

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

Provides explicit guidance on when to use this tool: open default, status=done/dismissed for closed history, project_id scoping. It also directs the agent to siblings for pending items and logbook actions, clearly stating when to use alternatives. Exclusions and conditions are spelled out.

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 the read-only/idempotent annotations by detailing the ranking logic (by question count, videos, citations), the inclusion of you_are_there, and the coverage statistics (videos with known channel vs still to establish). No contradiction with annotations; the content adds substantial behavioral context.

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

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

The description is verbose, containing long explanatory sentences about the Atlas structure and ranking rationale that are not strictly necessary for tool invocation. It could be shortened significantly to focus on the essential purpose and key behavioral details.

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

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

For a list tool without an output schema, the description sufficiently covers what the response contains (ranked channels with videos, questions, you_are_there, coverage stats). It is complete for an agent to understand the data returned, though pagination or limits are not mentioned.

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 already described in the schema (source_id as UUID, project_id with 'default' option). The description does not add extra semantics beyond what the schema provides, meeting the baseline of 3.

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

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

The description clearly states the tool lists channels behind a source, elaborates on the hierarchy (source vs channel), and explicitly frames it as reading the level below sources. This distinguishes it from sibling tools like list_sources and get_source, leaving no ambiguity about its function.

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

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

The description explains the context and what the tool does but does not explicitly tell when to use it over alternatives or when not to use it. It implies usage when a deeper view of a source's channels is needed, but lacks explicit direction or exclusion criteria compared to siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context beyond that: the 30-day scale, the distinction that 'no value is not a zero', domain folding, and the fact that the scale is stable across measurements and does not change with project_id. This informs the agent about data semantics and non-obvious behavior.

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

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

The description is long but densely packed with necessary context about the data model. It is front-loaded with the core purpose and then explains the scale, unit, and filtering nuances. No wasted sentences, though it could be slightly more structured with breaks, it remains readable and efficient.

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

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

Without an output schema, the description adequately explains what each entry contains (domain, AI Authority per AI, scale) and how filtering works. It lacks an explicit statement of the response format (e.g., a list of objects), but the prose strongly implies it. Given the complexity, this is nearly complete.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds meaningful nuance for project_id (explains that the scale does not move with it, enabling cross-project comparisons) and clarifies the meaning of the AI Authority scale referenced by the sort parameter. This goes 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 lists sources from the Atlas, each with AI Authority per AI. It distinguishes from siblings by explaining the data scope (the sources AIs cite) and the unit (registrable domain). The opening sentence is specific and not a tautology.

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

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

The description provides a clear use case: 'Use it to see where an answer comes from on a subject, and which places are worth existing on.' It does not explicitly name alternatives or exclusions, but the context is unambiguous; the detailed filtering options imply when to use it. No misleading guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds useful context: the content of each thread (question and answered status) and that threads are shared across members. This goes beyond the structured annotations and helps set expectations.

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

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

Two concise sentences with no filler. The core behavior (list support threads, most recent first) is front-loaded, and the shared-members detail is added without unnecessary verbosity.

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

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

For a list tool with no parameters and read-only annotations, the description fully covers what the agent needs: what is returned (threads with asked question and answered flag), ordering, and scope. No output schema is needed because the content is described explicitly. Nothing critical is missing.

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

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

The input schema has zero parameters, and schema description coverage is 100%. The description doesn't need to explain parameters; the baseline of 4 for no-parameter tools is appropriate, and it correctly omits any parameter discussion.

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

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

The description states a clear verb and resource: lists support threads. It specifies ordering (most recent first) and content (what was asked, whether answered). It's distinct from siblings like get_support_thread (which likely fetches a single thread) and contact_support (which creates).

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

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

The description clearly implies use for listing all threads and notes they are shared by account members. It does not explicitly mention when to use get_support_thread for a specific thread, but with zero parameters and a straightforward purpose, the usage is self-evident.

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, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds deep behavioral context: the derived statuses, the checklist semantics (required, kinds, custom, set-aside), the domain authority sourcing, and the meaning of null source_id. It explains edge cases (no zero for absent engines, deletion semantics) without contradicting 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 very long but dense and logically structured: it starts with the core definition, then checklist mechanics, statuses, domain authority, and finally parameters. It front-loads the most critical concept (surface vs corroboration) and each section builds on the previous. Some sentences are verbose and could be tightened, but the complexity justifies the length.

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

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

Given the tool's complexity and lack of output schema, the description fully explains what each surface carries (type, url, label, etc.), the checklist fields, derived statuses, domain authority sourcing, and both parameters. It covers all aspects an agent needs to invoke the tool correctly, including edge cases and exclusions.

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 substantial meaning beyond schema: sort explains the difference between registry order and authority order, and emphasizes it never filters; deleted explains the trash view and ordering. It also clarifies project_id via reference to list_projects. This elevates the parameter understanding well beyond the schema's enums.

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 the surfaces of a project, defines what a surface is (pages with final say by the customer), and explicitly distinguishes it from corroborations via list_corroborations. It covers the core resource and purpose without ambiguity.

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

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

It explicitly explains when to use this tool versus list_corroborations based on the control criterion, and says 'Start here to find a surface id,' providing clear context. The parameter descriptions for sort and deleted also give usage guidance, including that sort never filters and deleted='only' accesses trash.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral details beyond annotations: the ordering (followed first, then archived), the presence of an 'archived' boolean and 'archived_at' field, and the inclusion of 'recalculated cost per survey'. These specifics help the agent understand the response structure and ordering without an output schema.

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

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

The description is two sentences with zero waste. It front-loads the core function and returned fields, then adds filtering and ordering details. Every sentence earns its place, and the structure is easy to parse 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?

For a read-only list tool with one optional parameter and no output schema, the description covers the essential behavioral expectations: what fields are returned, the default ordering, and the archived flag. It does not mention pagination, but that may not be needed for this tool. Given the annotations already cover safety and the description covers the response shape, it is nearly complete. A slight gap is lack of an explicit example or error conditions, but these are minor for a list operation.

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

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

The single parameter project_id has 100% schema description coverage, so the schema already explains its meaning and the 'default' special value. The description adds only a brief mention ('Filter by project with project_id'), which is redundant with the schema. Per the rubric, with high coverage, baseline is 3; the description does not significantly enhance parameter understanding.

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

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

The description states a specific verb ('List') and resource ('trackers of the account'), and lists the included fields (configuration, status, keywords, analysts, project, recalculated cost). It clearly differentiates from sibling tools like create_tracker, update_tracker, and archive_tracker by being the listing operation. The phrase 'Start here to find a tracker id' reinforces its role as the entry point for tracker operations.

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

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

The description gives clear usage context: filter by project via project_id, and explains the ordering of results (active first, then archived). It does not explicitly name alternatives or when-not-to-use, but the tool name and verb make it obvious this is for listing, not for mutations. The 'Start here' hint implicitly tells the agent to use this before other tracker-related operations that need an 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?

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

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

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

Two sentences with essential information front-loaded. No redundant words; each sentence adds value.

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

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

Given the tool's simplicity (one parameter, no output schema), the description adequately covers the core behavior and state transition. It does not describe error handling or side effects for invalid inputs, but this is acceptable for a straightforward action.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is slightly longer than strictly necessary but every sentence contributes useful information. It is front-loaded with the core action and distinguishes from sibling tools without redundancy.

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

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

For a rename tool with no output schema, the description covers what changes and what doesn't, uniqueness behavior, idempotency, archived projects, and how to handle naming conflicts. It comprehensively answers likely agent questions.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds meaning by clarifying 'name' is the folder name (not the canon) and emphasizes uniqueness and case-insensitivity, providing extra semantic context beyond the schema.

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

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

The description clearly states the tool renames a project (the folder name), differentiating it from updating the canon via update_project_canon. It explicitly says 'Use it for the name of the folder; the wording of the brand itself is the canon, and it moves with update_project_canon.'

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

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

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

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

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

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

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

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

Three sentences: first explains core action, second clarifies idempotency and history preservation, third gives usage tip. No wasted words, front-loaded efficiently.

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

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

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

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

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

Schema coverage is 100% and its description already explains the quest_id parameter. The description restates the UUID context and the lookup method, adding no new semantic detail beyond what the schema provides.

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

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

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

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

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

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

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

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

The description elaborates on the idempotentHint annotation by stating 'Idempotent and never refused' and clarifying what happens with a domain that wasn't dismissed. It also explains that the operation affects the tracker's dismissed list, adding transparency beyond annotations.

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

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

The description is well-structured and packs significant information into three sentences. It could be slightly more concise, but it avoids redundancy and is front-loaded with the core purpose.

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

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

Given the lack of an output schema, the description adequately covers input behavior, parameter constraints, and the nature of the response (restored domain or list). It provides enough context for an agent to use the tool correctly.

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

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

The description adds crucial context beyond the schema: the mutual exclusivity of domain and domains ('send this OR domains, never both'), and the all-or-nothing behavior for the batch parameter. These details are not present in the schema descriptions.

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

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

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

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

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

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

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

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

Beyond the idempotentHint and non-destructive annotations, the description adds that the entry is restored with its annotation on curves. This supplements the structured data with meaningful behavioral context.

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

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

Two sentences, no fluff. The first sentence states the core purpose; the second provides usage guidance and explains idempotency. Every word earns its place.

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

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

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

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

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

The single parameter entry_id is fully described in the input schema with a usage hint. The tool description does not add new information beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('bring back'), the resource ('logbook entry'), and the key behavioral aspect ('with the annotation it placed on the curves'). It distinctly differentiates from sibling tools like delete_logbook_entry and create_logbook_entry.

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

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

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

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

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description aligns by stating 'bring back...as they were' and that restoring an already-registered surface returns the same. The description adds value by specifying what gets restored (sheet and alignment journal), though it could mention permissions or side effects.

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

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

The description is two sentences long with no extraneous information. It efficiently communicates the action, prerequisites, and idempotent behavior.

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

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

Given the single parameter, good annotations, and no output schema, the description is fully adequate. It covers how to find the input, what the tool restores, and the idempotent outcome, leaving no gaps for the agent.

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

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

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

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

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

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

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

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

The description explicitly instructs to call 'list_surfaces' with 'deleted' set to 'only' to find surfaces to restore, providing a clear prerequisite and alternative path. It also notes the idempotent behavior of restoring an already-present surface, giving precise usage guidance.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false. The description adds valuable behavioral context: it becomes 'work again' and needs verification, and it explains the source of valid checks (list_surfaces with deleted true). It also reinforces idempotency by stating restoring an existing check 'answers the same.' No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core action and immediate consequence. Every sentence earns its place: the first states what it does and its effect, the second provides the source for valid checks, and the third handles an idempotency edge case. No unnecessary words or filler.

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

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

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

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

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

Schema description coverage is 100% for both parameters (check and surface_id), so the baseline is 3. The description adds minimal extra meaning about parameters, only reinforcing that the check key comes from list_surfaces and restoring brings back cells. No significant parameter-level details beyond the schema.

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

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

The description clearly states the action: 'Bring a check of your own back to the checklist of a surface' with the specific resource (surface checklist) and verb (restore). It distinguishes itself from sibling tools like add_surface_check (adds new) and delete_surface_check (removes) by focusing on restoration of previously deleted checks.

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

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

The description gives clear context on when to use the tool: to restore checks that are marked 'deleted true' in list_surfaces. It also covers the edge case of restoring an already-existing check. It does not explicitly name alternative tools for adding or deleting checks, but the guidance is sufficient for selecting this tool over siblings.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Description clearly specifies the tool sets 'free addresses of the brand' and explains what those are (satellite domains, tracking links, etc.), distinguishing it from sibling tools like get_link_targets.

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

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

Explicitly advises calling get_link_targets first and confirming with user before replacing. Provides clear context but does not explicitly state when not to use.

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

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

The description discloses that the balance is debited, that results arrive within a few minutes, and that calling again on an already-armed scan returns the same result without charging. This adds valuable context beyond the annotations (readOnlyHint false, idempotentHint true) and fully aligns with 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?

Three sentences, each carrying essential information: the action and cost, the human approval requirement, and the idempotency/result retrieval. The capitalized 'SPENDS:' warning is a concise, effective structure.

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

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

Covers the key operational context: action, cost, approval, latency, idempotency, and how to retrieve results. However, it does not mention error conditions such as insufficient balance or what the immediate response contains, which would be useful for an agent.

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

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

The schema already provides a clear description for competitor_scan_id, including how to find it via list_competitor_scans. The tool description adds no further parameter-specific detail, so the baseline of 3 is appropriate given the high schema coverage.

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

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

The description opens with 'Arm a prepared scan' and clearly explains the action: the engine is asked and the prepaid balance is debited. This specific verb+resource+side-effect framing distinguishes it from sibling tools like create_competitor_scan, list_competitor_scans, and get_competitor_scan.

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

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

It explicitly instructs to read the amount to the person and get their go-ahead before calling, and directs users to get_competitor_scan for reading results. It does not explicitly exclude alternatives like create or update, but the context makes the appropriate use case 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?

With annotations already declaring readOnlyHint=false and idempotentHint=true, the description adds crucial extra behavior: the insufficient_credits refusal carrying a top_up_url for the user, and the idle effect of restarting an active tracker. It maps directly to the idempotentHint, and there is no contradiction with annotations.

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

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

Three concise sentences that front-load the primary action, then cover the conditional immediate-survey behavior, the credit error handling, and idempotency. No fluff; 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?

For a single-parameter mutation tool with no output schema, the description covers the main behavior, the conditional trigger, the idempotent nature, and the most important error case (insufficient credits) including how to guide the user. An agent has enough to call it correctly and handle the failure path.

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

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

The schema already describes tracker_id fully ('The UUID of the tracker: call list_trackers to find it.'), so coverage is 100%. The description does not add parameter-specific details beyond that, meeting the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('start'/'restart') and a clear resource ('measurement of a tracker against the prepaid credit balance'), and distinguishes itself from siblings like 'survey_now' and 'pause_tracker' by specifying the immediate-survey behavior and idempotency. The agent can tell exactly what this tool does and what it does not do.

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

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

The description explicitly states when the first survey runs ('there and then' unless a future next_survey_at exists) and that starting an active tracker changes nothing. This implies the agent should use a different tool (e.g., survey_now) for an unconditional immediate survey, though it does not name an alternative directly. Clear context without explicit 'use X instead' 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?

Despite no annotations carrying behavioral detail, the description discloses key behaviors: it debits credit, joins the score series as on_demand, handles concurrent calls by answering the ongoing survey, and explains two refusal conditions with specific error codes (insufficient_credits, tracker_not_active) and how to recover (top_up_url, start_tracker). This far exceeds the baseline and matches the readOnlyHint=false, destructiveHint=false annotations.

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

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

The description is long but each sentence delivers distinct, necessary information: core action, scheduling context, credit impact, result retrieval, concurrency behavior, and error handling. It is well structured with front-loaded purpose and no filler, though slightly dense; it earns a 4 rather than 5 because it could be trimmed slightly without losing value.

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

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

For a single-parameter tool with no output schema, the description covers all essential operational details: the action, interaction with schedule, financial effect, result linkage, concurrency safety, and error conditions with recovery paths. Nothing an agent needs to call it correctly or interpret outcomes is missing.

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

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

Schema coverage is 100% for the single parameter tracker_id, which already includes a description ('The UUID of the tracker: call list_trackers to find it.') and format uuid. The tool description does not add extra parameter-specific semantics beyond implying the tracker must be active and have credit, but that is contextual rather than parameter-level. 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 states a specific verb ('Run one survey') and resource ('measuring tracker') and clearly distinguishes it from scheduled surveys and the on_demand frequency special case. It also names related tools (get_results, get_responses, start_tracker) that serve different purposes, so an agent can select it correctly without ambiguity.

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

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

It explicitly states when to use the tool ('on top of its schedule'), when it applies to on_demand trackers, and when not to use it (tracker not active, insufficient credits). It also names alternative tools for reading results and starting the tracker, giving clear context and 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 state readOnly=false and idempotent=true, and the description aligns with these while adding extensive behavioral context: batch rejection on unknown items, canon stamping requirements, site-wide item semantics, refusal to set aside the last canon cell, and the impact on ALIGNED status. It clearly discloses error conditions and side effects beyond the annotations.

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

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

The description is lengthy but every sentence carries operational meaning. It is front-loaded with the core action and then details moves, constraints, and edge cases. It could be better structured with paragraphs or bullets, but it avoids redundancy and earns its length.

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

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

For a mutation tool with no output schema, the description thoroughly covers input semantics, failure modes, and side effects on checklist state and ALIGNED status. It does not explicitly describe the return value (e.g., what the updated checklist looks like), but given the idempotent, batch-oriented nature, the absence is not critical. The context provided is enough to invoke the tool correctly.

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

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

Schema coverage is 100% and the schema already describes each parameter well. The description adds higher-level semantics: the three moves (verify/set aside/clear), the meaning of omitted done/dismissed, the requirement of reason when dismissed, and the language handling for per-language vs site-wide items. This goes beyond what the schema alone provides.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100% with rich descriptions for both parameters (major vs minor units, examples like 50→50.00, 5000→50.00). The description adds decision guidance not in the schema: when to send which parameter, that they're mutually exclusive, and that amount should match exactly what the user said. This adds genuine routing value beyond the schema.

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

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

The description clearly states the verb (prepare top-up), the resource (prepaid credit balance), and the mechanism (returns hosted payment link). It distinguishes itself from siblings by being the only tool that handles payment/prepaid credits, and explicitly clarifies that nothing is charged by this call—a non-obvious behavioral detail that differentiates it well.

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

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

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

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

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

Annotations already indicate idempotency and non-destructiveness. The description adds crucial behavioral nuances: null clearing for some fields but preserving for others, field dependencies, and invoice effects. No contradictions.

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

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

The description is three well-structured sentences, front-loaded with the main directive. It covers key points without excessive verbosity, though it could be slightly more concise.

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

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

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

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

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

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

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

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

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

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

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

The description provides explicit guidance: send only changed fields, null behavior differs per field, billing_country must accompany address/VAT. It could be improved by explicitly stating when not to use this tool, but the current instructions are thorough for typical use.

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

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

Annotations already indicate idempotent and non-destructive, but the description adds significant context: replacement semantics for questions, cost behavior per rescan pass, no-op when setting same cadence, and that stopping cadence preserves data. This goes well beyond the structured hints.

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

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

The description is dense and front-loaded with purpose, but it is quite long. Every sentence earns its place, yet the prose could be tightened without losing meaning. Still, structure is logical: purpose, then parameter-specific behavior, then idempotency/cost notes.

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 two distinct modes, cost implications, idempotency behaviors, and edge cases (409, null cadence). The description covers all of these thoroughly, including what happens to the accumulated list when cadence stops. 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?

Despite 100% schema coverage, the description adds crucial meaning: questions list replaces rather than appends, omitted questions are removed, and cadence choices have strategic trade-offs (weekly spends more, monthly matches corpus pace). It also connects to estimated_cost_minor, providing cross-parameter context.

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

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

The description opens with a clear verb+resource statement: 'Correct a scan still in draft, and set the cadence of one already armed.' It explicitly distinguishes between two modes and implicitly differentiates from sibling tools like create_competitor_scan and start_competitor_scan.

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

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

The description provides explicit when-to-use guidance: draft vs armed scans, and notes that changing questions after measurement returns 409, implying the need to create a new scan instead. It also explains cost implications ('Nothing is charged until start_competitor_scan') and when to set cadence.

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

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

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

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

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

The description is dense but every sentence carries operational value: field-level update behavior, URL/source coupling, monitoring inclusion, and the archive alternative. It is well-organized, front-loaded with the core purpose, and avoids redundancy with the schema.

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

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