freedom-mcp

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

With no annotations, the description carries the full burden. It discloses idempotency (already-acked returns 'not found'), write-tier with approval requirements, and that ack can happen after execution or skipping. Provides good 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?

Front-loaded main purpose, followed by usage condition and tier note in brackets. Slightly verbose but well-structured with no redundancy.

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

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

For a simple ack tool with 2 params and no output schema, description covers purpose, usage, idempotency, and tier approval. Missing explicit success response but hints at behavior via idempotency note.

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

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

Schema coverage is 100%, baseline 3. Description adds origin for 'id' (from list_attention_directives or create response) and for 'companyId' clarifies membership and scope requirement, improving 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?

Description clearly states the action: 'Mark a pending attention directive as acked' after executing a directive. It specifies the actor (Grok/Claude/host builder) and distinguishes from siblings like cancel_attention_directive by focusing on acknowledging an executed directive.

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: after executing or deliberately skipping a directive you polled, for the same operator. However, it lacks explicit comparison to alternatives like cancel_attention_directive, though the use case is well-defined.

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 no annotations, the description carries the full burden of behavioral disclosure. It honestly communicates that the tool does not regenerate the whole plan and includes an approval-tier warning about manager approval for first use. It does not describe return values or error cases, but the key side-effect and permission context are present.

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 succinct sentences plus a short parenthetical alternative and an approval note. The main action and scope are front-loaded, and every sentence contributes meaningful guidance without repetition 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?

For a tool with a nested activity object and no output schema, the description conveys enough to start invocation: scope, alternative, and approval context. It could go further by hinting at success/error behavior, but the rich input schema covers the param details. The approval note is valuable contextual information not available elsewhere.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters. The description adds no additional parameter-level meaning beyond the schema; it only restates the intent of adding an activity. Baseline 3 is appropriate when 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 states a specific verb and resource: 'Add ONE activity to an agent's activity plan without regenerating the whole plan.' It clearly differentiates from sibling tools like recalibrate_agent_jd, update_agent_activity, and remove_agent_activity by emphasizing adding a single new deliverable rather than rebuilding or modifying existing plans.

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 tells when to use this tool: 'to give an agent a new recurring or one-off deliverable.' It also names the alternative for rebuilding the entire plan ('recalibrate_agent_jd with regenerate_activities=true instead'), giving the agent a clear routing decision.

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?

No annotations are provided, so the description carries the full burden. It includes the write-tier approval note, which is a behavioral trait, but lacks details on side effects, idempotency, or what happens after tracking. The description focuses more on usage than on behavioral implications.

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 four sentences that are front-loaded with purpose and usage. The write-tier note is separate but still relevant. Every sentence adds value, though the note could be more integrated.

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

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

For a tool with 6 parameters, no output schema, and no annotations, the description covers purpose and usage but lacks information about return values, error cases, or prerequisites. It provides adequate context for decision-making but is not fully comprehensive.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about life domains and pairing with save_knowledge, but does not significantly enhance the understanding of individual parameters 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 verb 'Track' and resource 'commitment, deadline, birthday, appointment, or obligation'. It explicitly distinguishes from save_knowledge and provides concrete examples of when to use.

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 'ALWAYS use this (not save_knowledge) when the user mentions...' and gives a comprehensive list of triggers. It also advises pairing with save_knowledge for supporting context, providing 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?

No annotations are provided, so the description carries the full burden. It discloses that evidence outranks generated ICP simulation, and includes a detailed approval note explaining tiers (first use may require approval, from-now-on vs just-once approval). While it doesn't discuss idempotency or error handling, the information about write-tier and approval behavior adds significant value beyond the schema.

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

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

The description is concise and well-structured. The first sentence states the core purpose. The second sentence clarifies priority over ICP simulation. The third sentence provides usage guidelines. The bracketed approval note is separate and informative. No unnecessary words 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 (11 parameters, no output schema), the description covers the essential aspects: what the tool does, when to use it, and important behavioral notes (approval, priority over ICP). It lacks explicit mention of return values (e.g., whether it returns the stored evidence ID) but that is common for write tools. The description adequately prepares the agent 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 description coverage is 100%, so baseline is 3. The description adds context for the 'class' parameter (determines rank weight) and provides examples for 'source' (e.g., 'support ticket #…'). The approval note explains the 'may_open_loop' and 'may_refine_icp' parameters implicitly. While the schema already describes each parameter, the description reinforces their meanings and adds behavioral nuances, elevating it above 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's purpose: 'Store one piece of REAL Customer Evidence for this company'. It enumerates specific types of evidence (paying-customer words/behavior, telemetry, review, etc.) and distinguishes it from ICP simulation, which is handled by a sibling tool (create_icp). This provides a specific verb-resource combination and differentiates from similar 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 explicitly specifies when to use the tool: 'Use when the operator pastes a real customer quote, a call note, a review, or a provenanced usage signal — NOT for inventing personas (use Customer Hunter / create_icp for hypotheses).' This provides clear context and explicitly excludes alternative scenarios, offering direct guidance on tool 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?

Without annotations, the description carries the full burden. It discloses idempotency, auto-triaging, and a write-tier approval process. It could be more specific about what 'auto-triaged' entails and if any other side effects occur, but generally it is transparent.

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 paragraphs with no unnecessary words. The first sentence immediately states the core purpose, and additional context is efficiently added. Every sentence adds value, and structure is well front-loaded.

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

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

Given no output schema and moderate complexity (9 params, 1 required), the description covers key aspects: what the tool does, idempotency, required fields, and approval. It does not explain return value (e.g., lead ID), but overall it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by stating 'Provide at least an email OR a name' (clarifying optionality) and noting idempotency on (company, email). This adds meaningful context for parameter combination.

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

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

The description clearly states the tool adds a lead to the Leads CRM (crm_leads), specifying the table and that it feeds the Leads tab, triage, and outreach. The verb 'add' and resource 'lead' are specific, and the context distinguishes it from sibling tools like update_lead.

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 good usage guidance: it mentions idempotency on (company, email), requires at least email or name, and includes a routing hint ('CRM/sales → add a lead or prospect → use this'). However, it does not explicitly mention when not to use it or contrast with alternatives like update_lead.

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, the description fully discloses the sensitive nature: 'Creates a Command Center approval card (sensitive, every call)' and explains the approval process, including that it requires manager approval, queues individual approval cards, and sends exactly once on approve. It also notes there is no standing grant, which is critical 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 well-structured with front-loaded purpose and clear sections. While it is a bit verbose (three paragraphs), every sentence contributes meaningful information. No redundancy, but could be slightly tightened without losing clarity.

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

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

Given no output schema, the description explains what happens on approval (invite email + roster row), covers all input parameters, the approval process, routing, and alternatives. It is comprehensive for a tool that adds a team member, leaving no critical gaps in understanding.

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

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

Schema coverage is 100%, and the description adds significant value: it clarifies that 'role' can be a job title or access preset ('team' or 'manager'), that 'name' is optional and derived from email if omitted, and that 'email' must be exact. It also reinforces the required parameters and their semantics beyond the schema.

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

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

The description clearly states 'Add one human teammate to the current company by email' and differentiates from siblings by referencing interview_for_hire for AI agents and get_team_members for viewing existing members. The verb+resource combination 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?

Provides explicit guidance: 'Use when the operator (or CoS) needs to add a person who is not yet on get_team_members.' Also states when not to use ('No bulk. No permission designer') and directs to alternative tools for AI agents and viewing existing members. The routing section clearly maps scenarios to 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?

No annotations are provided, so the description carries full burden. It discloses that it modifies operational state (inventory) and explicitly contrasts with storefront copy/price. It also flags the sensitive-tier approval requirement. This adds meaningful context beyond a simple 'adjusts inventory'.

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 and includes useful usage guidance and approval note. It is slightly repetitive (e.g., routing line) but each sentence adds value and does not waste words. Overall well-structured.

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

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

Given the tool has 4 parameters and no output schema, the description covers the necessary context: purpose, usage, boundary, and approval. It does not describe return values, but that is not required without an output schema. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional semantics beyond what the schema already provides; for example, delta is described in schema as 'Signed change to available quantity.' It does not enrich parameter understanding further, but it doesn't need to.

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 adjusts a variant's available inventory by a signed delta at its stocked location. It specifies the resource (variant) and action (adjust delta) and distinguishes itself from siblings by framing it as 'operational stock management' and noting it is not for storefront copy/price.

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: 'use when receiving stock, correcting counts, or reserving units.' Also includes a boundary note to prevent misuse. It does not name alternative tools, but the clear context and boundary make it easy to decide.

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?

No annotations are provided, so the description carries full burden. It discloses the write-tier nature, approval requirements ('first use may require a manager's approval; a from-now-on approval makes future calls seamless, a just-once approval re-asks next time'), and the effect of agreed=false ('clear the seal'). Also notes that Structured Plays refuse Run until this exists. This is rich behavioral context beyond simple mutation.

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

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

Front-loads the core purpose, then gives routing and approval context. It's a bit long but each sentence earns its place, covering usage, effect, and approval. The routing line is redundant with the first sentence but adds clarity.

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

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

Complete for a mutation tool: it explains the prerequisite (get_playbook), the consequence (run_playbook can dispatch), the effect on other tools (Structured Plays refuse Run), and the approval flow. With no output schema, it doesn't explicitly state the return value, but that's minor. The description covers the needed context well.

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

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

Schema coverage is 100%, so the schema documents all params. The description adds meaning for 'agreed' ('Default true. Pass false to clear the seal (required after the plan changes)') which supplements the schema. Also clarifies the alternative identification params (tactic_id or tactic_title). While the schema covers these, the description adds practical usage 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?

Clear and specific: 'Seal a Playbook plan... so run_playbook can dispatch.' Names the resource (source_details.plan_agreed_at) and the action (seal), and distinguishes from run_playbook and get_playbook. Also mentions it's the same seal Focus writes, adding context.

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

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

Explicitly states when to use: 'Use after get_playbook when the steps look right.' Also routes: 'Agree who does what on a Playbook → use this, then run_playbook.' This clear progression guides the agent compared to the numerous 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?

No annotations are provided, so the description carries the full burden. It describes the tool as a data-gathering operation (reads team context) and lists outputs, implying a read-only, non-destructive action. However, it does not disclose authorization details beyond being a member, rate limits, or response format specifics.

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 plus a short meta-instruction, all front-loaded with purpose and usage. No wasted words; the meta-instruction adds value for the agent's role. Slightly above average due to efficiency.

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

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

Given one required parameter, 100% schema coverage, and no output schema, the description adequately explains what the tool returns (composition, gaps, integration status) and provides usage examples. It is complete enough for an agent to understand and 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?

The single parameter 'companyId' has full schema coverage (100%) with a clear description. The tool description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states it gathers team/company context for talent strategy analysis and lists specific returns (team composition, growth signals, capability gaps, integration status). It specifies a verb (gather) and resource (team needs), but does not explicitly differentiate from sibling tools like get_team_roster or get_team_members.

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 lists example user queries that trigger this tool (e.g., 'what roles am I missing?') and clarifies that the tool gathers data while the agent provides recommendations. Lacks explicit when-not-to-use or alternative tool mentions, but the context is clear.

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

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

With no annotations provided, the description carries the full burden and does so well. It discloses the lesson is 're-injected at next voice mint', that content stays 'operator-authored' and doctrine is never invented, and details the write-tier approval workflow. This goes well beyond a basic write operation and helps the agent understand consequences.

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 paragraphs, front-loaded with the core purpose, followed by usage, constraints, behavioral effects, and approval notes. Every sentence adds value and there is no wasted wording, though it is slightly longer than strictly necessary due to the approval paragraph. Overall well-structured.

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

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

For a write tool with no output schema and no annotations, the description is remarkably complete. It provides the action, when to use it, content limits, what happens to the data, and approval requirements. All necessary context for correct invocation is present, making it self-sufficient.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds some context about lesson brevity and usage, but does not need to repeat what the schema already documents. It slightly reinforces the 'lesson' parameter semantics by saying 'what worked, what failed, which principle', but adds no new parameter-level details.

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 'Append one settleable CoS lesson for THIS operator only' — a specific verb, resource, and scope, which immediately distinguishes it from siblings like append_cos_preference and list_cos_lessons. It is a concise, action-oriented purpose statement.

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 'Use after a clear win/miss on a call' and specifies what to include ('what worked, what failed, which principle'), along with a constraint ('Short notes only — not transcripts'). It does not name alternatives or when-not scenarios, but the context is clear enough for an agent to decide appropriately.

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 no annotations, the description details durability, re-injection on next session, scope (this operator only), and first-use approval. However, it does not mention idempotency, rate limits, or error handling. Still, it provides substantial behavioral context beyond basic read/write classification.

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 paragraphs with clear front-loading of purpose and usage. The second paragraph about approvals is helpful but could be integrated more concisely. Overall, 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?

No output schema exists. The description does not specify the return value or success/failure indicators. While the tool is simple (append), the lack of output documentation leaves the agent guessing about the result of the operation. Adequate but not 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 3. The description adds meaning to the 'note' parameter with usage context ('Apply the note in the current call') and the length limit, but does not elaborate on 'companyId' beyond what the schema provides. Adds marginal 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?

Clearly states the tool appends a durable preference for this operator only, with specific use-case examples (hard to follow, cards sound, 'remember I prefer'). Distinguishes from the shared template by noting it does not edit the shared FreedomOS CoS template.

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 lists when to use ('when they say something was hard to follow...') and what not to do (does not edit shared template). Also provides approval tier information, guiding the agent on when permission may be needed.

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

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

With no annotations, the description carries burden. It discloses the write-tier operation and approval requirements, which is helpful. However, it misses other behavioral aspects like whether it returns appended rows or requires an existing spreadsheet.

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 the main action front-loaded. It is concise and efficient, though no structural formatting is used.

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 simplicity of the tool and high parameter coverage, the description is mostly adequate. However, it lacks return value information and does not differentiate from update_sheet, which might cause confusion.

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 parameters are fully documented in the schema. The description adds no further semantics beyond what is already in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool appends rows to a Google Spreadsheet, which is a specific verb+resource. It distinguishes from siblings like read_sheet and update_sheet by using 'append'.

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 no guidance on when to use this tool versus alternatives like update_sheet or read_sheet. It only mentions a write-tier approval, but no 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?

With no annotations, the description fully shoulders behavioral disclosure. It explains rejection behavior (leaves queue, never publishes), sensitive-tier with manager approval, and the distinction between from-now-on and just-once approval scopes.

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 paragraphs: the first is concise and front-loaded with the core action; the second adds necessary behavioral context. No redundant sentences, though slightly more context than strictly needed.

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 tool's functionality, usage triggers, and behavioral nuances. Lacks explicit mention of output or success/error responses, but parameters are well-defined in the schema. Overall sufficient for a focused 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%, so the schema already describes the three parameters adequately. The description adds minor context (e.g., approval scope note) but does not significantly enhance parameter understanding beyond schema documentation.

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

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

The description clearly states the tool approves or rejects a content item for publishing, with explicit verb–resource pairs and example user phrases. It distinguishes between the two modes (approved:true/false).

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 scenarios with example user utterances for both approve and reject. Lacks explicit mention of when not to use or alternative tools (e.g., publish_pipeline_item), but the examples are clear and actionable.

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 no annotations, the description carries full burden. It clearly states 'flips is_active off/on' and 'No data is deleted or cascaded.' It also mentions the approval requirement. Missing info on return value or error behavior, but core effects are transparent.

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 paragraphs with no redundant text. It front-loads the main action, provides usage examples, and includes a necessary approval note. Every sentence is justified.

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 (toggle, no output schema), the description covers the essential behavior and usage. However, it does not explain expected return or error states, which could be helpful for an agent.

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

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

Schema coverage is 100% and descriptions are clear. The description adds value by specifying that pipeline_id comes from list_pipelines and clarifying restore parameter semantics. This goes beyond the schema alone.

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 archives or restores a pipeline by toggling is_active. It distinguishes from other tools by explicitly likening it to the UI's soft-delete/restore. Example user phrases further clarify 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?

The description provides explicit usage scenarios (archive, pause, restore) and notes the restore:true parameter. The write-tier approval note adds context. However, it does not discuss fallback or error cases, or explicitly contrast with sibling tools like update_pipeline.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It informs that the delete is safe and recoverable, and mentions a write-tier requiring possible manager approval, which is valuable context about side effects and authorization. It does not detail all consequences, but the core behavior is transparent.

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 and well-structured: it states the purpose, the usage trigger, and the approval note in only a few lines. No extraneous information is present, and key details are front-loaded.

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

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

For a simple archiving operation, the description covers the main action, the identification method, and approval requirements. The only minor gap is not explicitly stating that at least one of tactic_id or tactic_title is required (though implied), and not mentioning edge cases like no match found. Overall it is sufficient for an agent to call correctly.

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

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

Schema description coverage is 100%, and the description only restates 'Identify by title or ID' which the parameter descriptions already convey. It adds no new meaning about how to choose between tactic_id and tactic_title or what happens if both are provided, so it provides minimal 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 action ('Archive a Playbook') and the resource, with the qualifier 'safe delete — recoverable' adding precision. It distinguishes this from sibling tools like create/update/run playbook by specifying the retire use case, making the intent unambiguous.

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

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

It explicitly says 'Use when the operator wants to retire a playbook' and repeats this in the Routing line, giving a clear condition for when to invoke. It doesn't list alternatives or explicitly state when not to use, but the purpose is distinct enough among siblings that the guidance is sufficient.

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

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

No annotations provided, so description carries full burden. It clearly discloses that the tool mutates state: changes card status to approved, product_status to fixed, adds history comment, and notifies filer. Also mentions write-tier and approval requirements, providing full transparency.

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

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

Very concise: two short paragraphs. First gives purpose and usage, second adds approval context. No fluff, every sentence is valuable.

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

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

Despite no output schema, the description covers all necessary context: what the tool does, when to use it, what side effects it has, and authorization requirements (write-tier, approval). No gaps.

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

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

Schema coverage is 100% and the description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate since no extra parameter details are needed.

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 provides a specific verb ('attach'), resource ('GitHub PR URL'), and outcome ('resolve by construction'). It clearly distinguishes itself from siblings like submit_product_request by stating it closes the request automatically.

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: when you or a coding agent opened a real PR. Mentions that no separate human close step is needed. Does not explicitly specify when not to use or list alternative tools, but the context is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool sends queries to external LLMs, checks responses for brand mentions, and does not answer questions or delegate work. This covers key behavioral traits sufficiently, though it omits details like rate limits or cost implications.

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: the first states the core action, the second adds detail, and the third clarifies boundaries. It is extremely concise, front-loaded, 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?

The description explains the tool's purpose well but does not describe the output format, which is important since no output schema is provided. Agents cannot predict whether the result is a boolean, a list of mentions, or a detailed report. This is a notable gap given the 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?

Schema coverage is 100%, so baseline is 3. The description provides context for 'providers' (listing example engines) and 'prompt' (example query) but does not add significant semantic value beyond the schema descriptions. It is adequate but not exceptional.

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 'Audit' and the resource 'whether Freedom OS appears in AI-generated search results'. It differentiates from siblings by specifying it tests multiple external AI engines and is for brand visibility. It also explicitly states what it does NOT do, leaving no 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?

The description positions the tool as a competitive SEO/GEO auditing tool and clarifies it is not for general Q&A or delegation. This helps agents infer when to use it, though it does not explicitly list alternative tools or scenarios to avoid.

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 mentions a write-tier requiring manager approval, which adds some behavioral context. However, without annotations, it doesn't disclose potential side effects, reversibility, or resource impact beyond the approval note.

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 clear first sentence. The approval note is extra but not excessive. Could be slightly more structured.

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

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

For a complex tool requiring JSON requests, the description lacks details on return values, error handling, or how to construct requests. No output schema exacerbates this.

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

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

Schema coverage is 100%, so the schema already fully documents parameters. The description adds no extra meaning beyond restating 'batch operations' and giving vague examples.

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 performs batch operations on a Google Spreadsheet, with examples like formatting and merging. This distinguishes it from sibling tools like update_sheet or append_to_sheet.

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

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

No explicit guidance on when to use this tool versus alternatives like update_sheet or append_to_sheet. The approval note is behavioral context, not usage comparison.

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?

No annotations are provided, so the description carries full burden. It discloses that the tool uses a real browser, takes a screenshot, and returns page content and image. The sensitive-tier approval note adds transparency about authorization. However, it lacks details on what 'page content' includes (e.g., full HTML or text) and any limitations, which would improve transparency.

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

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

Two concise sentences with a bracketed note for the approval process. Front-loaded with the core action and returns, then use cases, then administrative info. 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 no output schema, the description should detail return values. It mentions 'page content and a screenshot image' but does not specify what page content entails (e.g., rendered text, full HTML) or image format. For a browsing tool, these are important missing 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 description coverage is 100%, so baseline is 3. The description repeats the schema details (url must include protocol, optional actions) but does not add new meaning or constraints 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 clearly states the tool's purpose: 'Browse a web page in a real browser and take a screenshot. Returns page content and a screenshot image.' It uses specific verbs and resources, and distinguishes from sibling tools like read_web_page by emphasizing visual needs and JavaScript interactivity.

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: 'Use when you need to SEE what a page looks like (visual audit, brand check), interact with JavaScript-heavy pages, or capture visual evidence.' This tells the agent when to choose this tool over alternatives, and also mentions the sensitive-tier approval process.

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 no annotations, the description discloses key behaviors: cancellation of pending directives, no reversal of completed work, operator-scoped, and approval tier. Lacks details on idempotency or error states but is sufficient.

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?

First paragraph is concise and front-loaded. Second paragraph adds useful approval context but is slightly verbose. Overall well-structured.

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

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

Covers purpose, usage, scope, and behavioral constraints adequately. No output schema, but return behavior is implied. Missing some edge cases but sufficient for a cancel 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%, so description adds no extra parameter meaning beyond the provided descriptions. Baseline score 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 'Cancel a pending attention directive' with specific use cases ('operator changed mind / wrong target'), distinguishing it from siblings like create_attention_directive and ack_attention_directive.

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 ('operator says drop/cancel' or 'CoS realizes wrong target'), includes an exclusion ('Does not reverse work the host already did'), and provides approval context. Guides the agent effectively.

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 no annotations, description provides critical authorization context (write-tier approval note) but doesn't elaborate on side effects like reversibility or notifications.

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 plus a useful warning in brackets. Front-loaded with purpose, then usage, then note. 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?

Covers purpose, usage, and authorization. Lacks details on post-cancel behavior (undo, logging) but adequate for a simple mutation with no 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 coverage is 100% so parameters are already well-documented. Description adds no additional meaning beyond what 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?

Description clearly states the action: 'cancel a commitment without completing it — marks it cancelled.' Uses specific verb and resource, and distinguishes from sister tool complete_commitment.

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

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

Explicitly tells when to use: for cancellation requests like 'cancel that', and when not to: for finished work, use complete_commitment instead.

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?

Since no annotations are provided, the description includes important behavioral context about approval tiers (write-tier, first use may require approval). This adds value beyond the schema.

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

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

The description is two sentences plus a parenthetical note, front-loading purpose and usage. Every part is concise and informative.

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

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

Given the tool has 3 parameters and no output schema, the description adequately covers purpose, usage, and approval behavior. It could mention what is returned after capture, but is still complete for its 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 the descriptions of parameters (content, companyId, source_url) are already present in the schema. The tool description does not add extra meaning for the 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 clearly states the verb 'capture' and the resource 'Ideas', with further explanation of saving for later. It distinguishes the tool from siblings like delete_idea and triage_idea.

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 'Use when user shares an idea they want to save for later', providing clear context. However, it does not explicitly state when not to use it or suggest alternatives.

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

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

Describes the two-step process (real evidence then simulation) and what feedback is returned (engagement, scroll past, missing). With no annotations, this disclosure is valuable, though missing details on permanence 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?

Three sentences, front-loaded with action, no fluff. Efficiently communicates tool purpose, process, and usage.

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

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

Adequate but lacks details on return format/structure, which would be helpful given no output schema. The description outlines what feedback covers but not its shape.

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

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

Schema coverage is 100%, so the description adds no additional parameter-level meaning beyond the existing schema descriptions. Baseline score 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 simulates customer feedback using real evidence or ICP, with a specific verb 'run past' and resource 'customer truth'. It is distinct from any sibling tools.

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

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

Explicitly advises use on 'customer-impact deliverables before sending', providing clear context. Does not specify when not to use or mention alternative tools, but the guidance is direct.

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 no annotations present, the description carries the full burden and does it well: it discloses idempotency, states existing projects are left in place and Workers scripts are never overwritten, and explains the write-tier approval behavior. It does not describe return format or possible failure modes, but it covers the most consequential behavioral traits clearly.

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 compact, well organized into purpose, idempotency, usage, routing, and approval note. It front-loads the main purpose and presents routing in scannable lines without redundant prose.

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 7-parameter write tool with no output schema, the description is nearly complete: it names prerequisites (standing token, connection status), routing, idempotency, and approval context. The only notable absence is what a success/failure response looks like, which keeps it from a full 5.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description adds only a light mapping of 'GitHub source (Pages)' and 'hostname (CNAME)' to parameter concepts, which is consistent but not a major semantic increment beyond the schema.

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

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

The description opens with a specific verb+resource: 'Claim or create a Cloudflare Pages or Workers project' on the company's standing deploy token. It goes beyond a generic label by naming exactly what the tool produces and by explicitly routing around siblings such as request_connector and get_cloudflare_hosting_status.

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 'Use when' statement plus the 'Routing' block explicitly tells an agent when to select this tool, when to use request_connector instead, when to use get_cloudflare_hosting_status, and which sibling not to use (invoke_integration). This leaves little to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It honestly states the tool's scope (does not execute or open PR) and mentions approval nuances ('first use may require manager's approval'). It also notes that it pins the frontier coding model. This is transparent for a write-tier tool.

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

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

The description is a single paragraph but efficiently conveys purpose, limitations, usage context, and permissions. It is front-loaded with the core action. The write-tier approval note is appended usefully. Some jargon ('paste-ready', 'Harness + gstack') may slightly reduce clarity, but overall it's concise.

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

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

Given the tool has 3 parameters and no output schema, the description covers its role in a workflow, when to use it, and behavioral boundaries. It explains the approval model. However, it does not describe what the claim recipe looks like or what happens after minting, which could be more complete 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?

Input schema has 100% coverage, so the baseline is 3. The description adds minimal extra context beyond the schema; it mentions stamp_claim defaults to true and relates to the claim recipe, but doesn't explain the companyId or request_id beyond what the schema already provides. It does not compensate for any gaps.

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

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

The description uses the strong verb 'Mint' and specifies the exact resource 'Builder claim recipe for a FreedomOS product request'. It clearly distinguishes that this tool prepares a recipe for a coding agent but does not execute it, differentiating it from siblings like submit_product_request or open_product_request_draft_pr.

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

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

The description states explicitly when to use ('after product team accepted the request') and what it does NOT do ('Does NOT run the coding agent or open a PR by itself'). It also limits usage to 'FreedomOS product-inbox members only'. While it doesn't name specific alternative tools, the behavioral exclusion provides 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?

With no annotations provided, the description carries the full burden. It states the tool is a write-tier action requiring approval, implying destructive behavior. However, it does not disclose whether the action is reversible, what the response is, or any side effects beyond 'start fresh'.

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: purpose, usage triggers, and approval note. It is front-loaded and every sentence adds value. No redundancy or unnecessary 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?

Given no output schema and no annotations, the description covers purpose, usage triggers, and permission requirements. It does not explain return values or how to verify the reset, but for a straightforward destructive action, the context is largely complete. Missing mention of using list_pipeline_learnings to check before resetting is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond what the schema already provides for parameters. It restates pipeline_id and mentions output_format behavior ('clears all formats if not specified'), but this is already in the schema description.

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

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

The description clearly states the tool's purpose: 'Reset all learnings for a pipeline and start fresh.' The verb-resource pair is specific. Example user phrases distinguish it from siblings like 'list_pipeline_learnings' or 'update_pipeline_style_guide'.

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 lists when to use the tool (e.g., when user says 'forget what you learned') and includes a note about write-tier approval. However, it does not provide when-not-to-use guidance or mention alternative tools like 'list_pipeline_learnings' before resetting.

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?

No annotations are provided, so the description carries the full burden. It adds behavioral info about write-tier approval (first use may require manager approval, approval types). However, it does not disclose other behaviors like state changes 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 concise: two sentences plus a helpful bracket note about approval. It is front-loaded with the purpose and 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?

Given the tool's simplicity (3 params, no output schema), the description covers purpose, usage context, and approval behavior. It could mention what the return indicates, but overall it is adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond the parameter descriptions already present in 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: 'Mark a commitment as completed.' It uses a specific verb ('complete') and resource ('commitment'), distinguishing it from siblings like 'cancel_commitment' or 'add_commitment'.

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

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

The description provides explicit usage context: 'Use when the user says they finished something or a deadline has passed.' It does not list alternatives or exclusions, but the context is clear enough to guide 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?

With no annotations, the description must cover behavioral traits. It discloses the approval constraint and per-widget scope. However, it does not mention that updates overwrite existing widgets, potential failure modes, or whether the tool is idempotent. Adequate but not comprehensive.

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

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

The description is extremely concise: one sentence for purpose, one for scope, and a bracket note for approval. No redundant information; front-loaded with key purpose.

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

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

Given 8 parameters with nested config and no output schema, the description gives an overview of widget types and the approval requirement. However, it does not describe the return value or common error scenarios, leaving some gaps for a complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal parameter meaning beyond the schema; it provides context for widget types and approval tier but does not enhance understanding of individual parameters beyond what the schema already describes.

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

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

The description clearly states it creates or updates a widget on the agent dashboard, specifying the verb ('Create or update') and resource ('widget'). It lists supported widget types and distinguishes from sibling tools like list_dashboard_widgets and remove_dashboard_widget by focusing on mutate 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 says to use it to display key metrics and notes that each call handles one widget. It mentions write-tier approval requirements. However, it does not explicitly state when to use alternatives or when not to use it, missing some decision 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?

With no annotations, the description carries full burden. It discloses that the tool 'Runs the SAME process-approval pipeline as tapping Approve on the card — does not bypass integrity rails.' It also explains the write-tier and the effect of 'from-now-on' vs 'just-once' approvals, providing behavioral context beyond the basic operation.

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

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

The description is extremely concise: two sentences plus a parenthetical note. It is front-loaded with the core purpose and usage, and each sentence provides essential information without redundancy. No wasted words.

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

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

For a confirmation tool with 6 parameters and no output schema, the description covers usage, behavioral transparency, and the write-tier note. It could detail error cases (e.g., invalid approval_id) or return behavior, but given the tool's simplicity, it is adequately complete.

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

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

Schema coverage is 100%, so the schema already documents all 6 parameters. The description adds value by explaining the relationship: 'Pass approval_id from the approval_required tool result' and clarifying the grant_mode options ('once' for one-time, 'standing' for future grants). This extra context helps the agent understand parameter usage beyond schema descriptions.

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

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

The description clearly states the tool's action: 'Confirm a pending MCP capability approval by spoken (or chat) yes/no.' It specifies the resource (MCP capability approval), the decision values, and the required approval_id. It differentiates from siblings by being the sole tool for approving MCP capabilities, distinct from other approval tools like 'approve_pipeline_item'.

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

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

The description provides explicit usage guidance: 'Use on voice when the operator says approve/yes or reject/no after a capability ask' and warns 'Do NOT invent an approval_id.' It also clarifies that it runs the same pipeline as tapping Approve on the card. However, it lacks explicit 'when not to use' scenarios.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so well. It reveals the asynchronous, polling-based behavior, clarifies that the tool does not directly manipulate the external UI, and discloses the write-tier approval requirement with specifics about one-time versus ongoing approvals. This is valuable non-obvious 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 information-dense but well-organized, with the core action stated first followed by behavior, usage triggers, parameter guidance, and approval context. It is slightly longer than strictly necessary, but the added detail is functional rather than fluff, so it earns a high score rather than a perfect one.

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

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

Given no output schema and no annotations, the description provides strong contextual completeness: it covers purpose, asynchronous behavior, when to use, parameter matching, host examples, and approval implications. It does not describe the return value or post-queue confirmation, but for a queue-style tool this is a minor omission.

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 all parameters with descriptions, so the baseline is 3. The description adds meaningful value by giving concrete examples for target_session_id (grok-<id>, claude-<id>, grok-bot-<agent-slug>) and reinforcing the polling match requirement, which helps an agent choose and populate the parameter correctly.

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: 'Queue a short instruction for an external agent session.' It clearly distinguishes this tool from sibling attention-directive tools by emphasizing it does not interact directly with the host UI and instead relies on the host polling FreedomOS. This makes the tool's unique 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 explicitly states when to use the tool: 'Use when the operator says "tell Grok…", "have Claude…", "send this to my Grok Bot…", or CoS should route reversible work off the call.' It also provides an important exclusion by noting the tool does not type into the UI and that the session must poll, giving clear guidance on operational 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?

No annotations exist, but the description discloses the write-tier approval process and hints at downstream use (Content Pipeline). Lacks details on idempotency or uniqueness constraints.

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

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

Two paragraphs with clear purpose and behavioral note. Could be more structured (e.g., bullet points for triggers), but no unnecessary words.

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

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

Covers purpose, triggers, and a key behavioral aspect (approval). Given no output schema and 8 parameters (2 required), the description adequately supports tool selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter context beyond the schema 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 adds a new feature to the Feature Index, specifies trigger phrases like 'I built X', and distinguishes from sibling tools (e.g., update_feature, list_features).

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 use cases and trigger phrases, but does not mention when NOT to use or name alternative tools for related actions like updating or retiring features.

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?

No annotations are provided, so the description carries the full burden. It includes a note about write-tier approval behavior, which is useful for understanding permissions and usage flow. This adds valuable context beyond a simple 'create' statement.

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 short and front-loaded with the core purpose. Every sentence adds value: the first explains what and how, the second gives usage examples, and the bracket note adds behavioral context. 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 creation tool with two parameters and no output schema, the description adequately covers purpose, usage, and approval behavior. It lacks details on potential errors or return values, but these are not critical for a straightforward creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the example from the schema (nested paths) but does not add new meaning beyond what the schema already provides. It offers no further parameter guidance.

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

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

The description clearly states the tool's function: creating a folder in the knowledge base for organizing files. It explains support for nested paths and provides use cases (deal rooms, topic grouping). This distinguishes it well from other tools in the sibling list.

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 specific use cases ('Use for deal rooms, topic grouping, or any organizational structure'), giving clear context for when to use the tool. However, it does not explicitly state when not to use it or compare it to alternatives.

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

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

No annotations, so description must disclose behavior. Mentions default formatting and approval requirement, but does not detail side effects, response behavior, or resource limits. Adequate but not comprehensive.

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 paragraphs; first paragraph states purpose, second adds approval notes. No fluff, but the approval note interrupts flow slightly. Still 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?

No output schema, and description does not explain return value or confirmation behavior. For a create tool with 5 params and 3 required, missing outcome info reduces completeness.

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

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

Schema covers all 5 params (100%). Description adds no new parameter details beyond what schema provides. Baseline score 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?

Clearly states action (create) and resource (Google Doc), specifies folder location ('user's Freedom OS folder'), and lists use cases (JDs, deliverables, shared documents). Easily distinguishes from siblings like update_google_doc and read_google_doc.

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 context: 'Use for JDs, deliverables, and shared documents.' Includes approval tier note, but lacks explicit exclusions or alternative tools. Still clear enough for 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?

Since no annotations are provided, the description carries the full burden. It adds important behavioral context: the write-tier approval behavior (manager approval required on first use, with options for ongoing or one-time approval). This is valuable beyond the basic purpose. However, it could spell out that this is a mutating operation that creates a permanent record, but that is implied.

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: two short paragraphs front-loading the main purpose and usage, followed by a note on authorization. No wasted sentences, every line 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 (13 parameters, nested objects, no output schema), the description covers the core purpose, usage guidelines, and authorization behavior. It could mention what the return value is (e.g., confirmation, ICP ID) but since no output schema exists, the description is not deficient. The nested object details are covered in the schema.

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

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

The schema has 100% coverage with descriptions for all 13 parameters. The description does not add additional parameter-level information beyond the schema; it focuses on overall usage. Therefore, it meets the baseline for 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 explicitly states the verb 'Create' and resource 'Ideal Customer Profile (ICP)', and distinguishes it from update_icp. It also mentions the specific condition (hasICPs:false) and the alternative tool, making the purpose very 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 provides explicit guidance on when to use this tool (when get_icps returns hasICPs:false or to add another profile) and when not (to change existing, use update_icp). This is perfect 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?

With no annotations, the description fully carries the behavioral disclosure burden. It usefully discloses the write-tier approval workflow, including how different approval types affect future calls. However, it does not describe return values, failure modes, or what side effects occur beyond creation.

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 compact and front-loaded with the core action, followed by a helpful definition and a clearly separated approval note. Every sentence earns its place with no repetition 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 12 parameters, no annotations, and no output schema, the description provides only the essential workflow context and approval behavior. The detailed schema compensates for parameter semantics, but the description lacks information about expected return values and how this tool fits alongside generate_key_results or update_key_result.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description adds only the general guidance that the parent objective can be identified by title or ID, which maps to objective_title and objective_id but does not meaningfully supplement the rich schema details.

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 specific action ('Add a key result to an objective') and defines what a key result is in OKR terms. It distinguishes this from related tools like create_objective by explicitly naming the parent relationship and allowing identification by title or ID.

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

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

The description gives clear context for when to use the tool — when adding a KR to an existing objective — and provides guidance on how to reference the parent objective. It does not explicitly mention alternatives like generate_key_results or update_key_result, so it falls short of a full 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?

No annotations are provided, so the description must disclose behavioral traits. It describes the artifact as 'persistent' and includes a detailed approval tier note about first use, manager approval, and approval types. This adds meaningful behavioral context beyond the schema.

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

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

The description is concise with two clear sentences plus a brief approval note in brackets. It front-loads the purpose and usage guidance. The bracketed note, while informative, slightly disrupts flow but is justified by its importance.

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 (3 required params, no output schema), the description covers purpose, when to use, and behavioral details. It lacks specifics on what happens after invocation (e.g., return value or artifact ID), but for an initialization tool this is sufficient for agent decision-making.

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 for all three parameters. The description does not add significant meaning beyond the schema—it mentions 'persistent Master Plan artifact' but does not elaborate on parameter usage or constraints. Baseline is 3 due to 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 verb ('Initialize') and resource ('a new multi-step project with a persistent Master Plan artifact'). It provides a directive to call this before complex tasks. However, it does not explicitly differentiate from sibling tools like 'create_folder' or 'create_feature', which could cause ambiguity for an AI agent.

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 'Call this BEFORE starting any complex, multi-tool task', giving clear when-to-use guidance. The approval note adds context about permission requirements. However, it lacks explicit 'when-not-to-use' or alternative tool references.

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 no annotations, the description carries full burden. It discloses that the ad draft is created in PAUSED state and spends nothing, and that activation is separate. It also mentions the sensitive-tier approval requirement. No contradictions.

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

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

The description is two concise sentences plus a brief bracketed note. It is front-loaded with the main purpose and behavioral trait, then usage guidance, then approval context. No unnecessary words.

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

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

Given the complexity (10 parameters, nested objects, no output schema), the description adequately covers overall behavior, usage, and approval. It could be improved by mentioning what the tool returns (e.g., ID of created draft), but it is largely 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 description coverage is 100%, so all parameters are documented in the schema. The description does not add additional meaning beyond what the schema provides, meeting the 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 'Create a complete Meta (Facebook/Instagram) ad draft — campaign + ad set + creative + ad — ALL in PAUSED state, spending nothing.' It specifies the verb 'create' and the resource 'ad draft', and distinguishes from sibling tools like set_meta_ad_status (activation) and update_meta_ad_budget.

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 'Use when the user wants to set up or draft an ad. Activation is a separate human-approved step (set_meta_ad_status).' It also provides approval tier guidance in brackets, explaining when manager approval may be needed and how approval types work.

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?

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the 'write-tier' nature and potential approval requirements on first use (with different approval types explained). This adds valuable transparency beyond what the schema provides.

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

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

The description is well-structured and front-loaded with the core purpose. It includes some workflow information and approval details, which are relevant but slightly extend beyond essential conciseness. No waste, but 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?

Given no output schema, the description adequately covers the tool's context: what it does, how to use it, next steps, and behavioral caveats. It provides a complete picture for a creation tool, though return values 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?

The input schema has 100% description coverage, so baseline is 3. The description adds minimal semantic value, e.g., emphasizing that description should not include key results. This is useful but not substantial.

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 creates a new objective (the O in OKR), defines it as aspirational goals, and distinguishes it from related tools like generate_key_results and create_key_result by providing a workflow. This makes the purpose 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 explicit guidance on when to use this tool (to create an objective) and recommends a workflow: after creation, use generate_key_results then create_key_result. It does not explicitly state when not to use, but the context given is sufficient for appropriate tool 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does it well. It states that the action does not charge FreedomOS, does not move money until the payer pays, returns a checkout URL, and includes write-tier approval semantics. This gives an agent a clear picture of side effects and prerequisites.

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

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

The description is front-loaded with the core action and purpose, then gives usage conditions, return value, side effects, and approval notes in a compact, well-organized format. Every sentence adds practical value, and the approval bracket is useful rather than 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 tool with 5 parameters but no output schema, the description covers the key runtime facts: what it returns, prerequisites, side effects, and approval behavior. Combined with fully documented parameters in the schema, an agent has enough information to invoke this tool correctly without additional inference.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description in the schema. The tool description adds overall context and the amount-building context, but it does not add significant per-parameter meaning beyond what is already structured. Baseline 3 is appropriate here.

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 and resource: 'Create a Stripe Payment Link', and explains the purpose with concrete use cases (sponsor, invoice, one-off). It also states the return value ('checkout URL') and includes a routing line that directs the agent to this tool for payment-link-related actions, distinguishing it from other payment-related 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 usage conditions: use when get_receive_status says charges_enabled or start_company_receive has finished, and it explicitly states 'Requires charges_enabled.' This is strong guidance. However, it does not explicitly mention when not to use this tool or name an alternative tool for other payment workflows, so it falls just short of a 5.

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

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

With no annotations, the description must disclose behavior. It explains the write-tier approval flow (first use may require manager approval, from-now-on vs just-once). It also mentions that social_post requires the 'gated publish owner.' However, it does not detail what happens immediately after creation (e.g., whether the pipeline is active, any default settings).

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 mostly concise and front-loaded with the main action. It contains a long list of output types and a parenthetical approval note, but every sentence adds value. Minor redundancy in the output list could be tightened.

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

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

Given the tool has 5 parameters (including nested inputs) and no output schema, the description covers inputs and outputs adequately but lacks details on the pipeline's lifecycle post-creation (e.g., whether it is immediately active, how to manage it later). The approval flow is a helpful addition, but overall completeness is moderate.

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

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

Schema coverage is 100%, so the description's added value is considered. It expands on the output enum (e.g., linking customer_newsletter to Email MCP, social_post to gated publish owner) and clarifies the approval implications. This exceeds 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 purpose: 'Create a new content pipeline to automate content creation.' It lists specific use cases (e.g., 'set up a changelog', 'create a newsletter pipeline') and output types, distinguishing it from siblings like update_pipeline or list_pipelines.

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 tells when to use the tool: 'Use when user says...' and explains output types with conditions (e.g., 'customer_newsletter... requires user Email MCP'). It also includes the write-tier approval behavior, guiding the agent on authorization needs.

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 no annotations, the description carries the full burden of behavioral disclosure. It transparently notes the write-tier nature and approval flow: 'first use may require a manager's approval; a from-now-on approval makes future calls seamless, a just-once approval re-asks next time.' It also clarifies the operational scope (company-scoped, Plays rail). While it does not detail side effects like idempotency or return values, the explicit approval mechanism is valuable behavioral context beyond the bare 'create' action.

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 and well-structured: a single purpose sentence, a routing directive, and an approval note. It front-loads the essential purpose and usage, with every sentence earning its place. There is no redundant content; the routing and approval notes are additive and directly useful.

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 8 parameters and all required fields clearly described in the schema, the description provides the necessary usage context (when to use vs. save_knowledge) and the write-tier approval behavior. It does not explain potential default values (e.g., status defaults) or behavior on duplicates, but these are minor gaps given the schema coverage and the explicit routing. Overall, it is sufficiently complete for an agent to call this 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 schema already describes all 8 parameters with 100% coverage, including enums and detailed descriptions (e.g., category meanings, linked_kr_id validation). The description adds no additional parameter-level nuance—it only restates the 'company' scope that is already in the schema. Since the schema carries the full weight, the baseline score 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 states a specific verb and resource: 'Create a Playbook for the company (growth_tactics — the Plays rail).' It explicitly contrasts with Knowledge files ('not a Knowledge file') and names the sibling save_knowledge, distinguishing this tool from the nearest alternative. This makes its purpose unambiguous and readily differentiated 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?

Explicit usage direction is provided: 'Use when the operator wants a reusable runnable loop or playbook — not a Knowledge file.' It further gives a clear routing rule: 'Playbook / reusable company loop → use this. SOP / guidelines / notes → save_knowledge.' This tells the agent exactly when to use this tool and when to choose the alternative, leaving no ambiguity.

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 no annotations provided, the description carries the full burden of behavior disclosure. It discloses that the tool only drafts (does not run), mentions human review, and includes a sensitive-tier note explaining approval persistence (from-now-on vs just-once). This is valuable context. However, it does not fully explain what output the Play contains (e.g., steps, custom instructions) or any side effects beyond drafting, so it falls short of a 5.

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

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

The description is succinct, front-loading the core purpose in the first sentence, then clarifying what it does not do, and adding usage and sensitive-tier context in subsequent lines. It is well-structured and avoids redundancy, though the sensitive-tier note adds a separate block that could be integrated more cleanly.

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 11 parameters, no output schema, and no annotations, so the description must provide substantial context. While it explains when to use and the approval flow, it does not describe what a successful draft returns, how to structure draft_* parameters, or what 'growth_tactics with steps' entails. The missing parameter semantics and lack of output expectation leave the description incomplete for reliable invocation.

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

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

Schema description coverage is only 36%, and the description does not elaborate on the parameters. It references 'activity_name' implicitly as the oversized activity and mentions 'growth_tactics with steps' which loosely maps to draft_steps, but it provides no semantic detail for draft_title, draft_category, draft_goal_impact, draft_custom_instructions, or other parameters. The description fails to compensate for the low schema coverage, leaving agents without adequate parameter guidance.

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

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

The description clearly states the tool drafts a Play from an oversized agent activity, with a specific verb (draft), resource (Play), and source context. It explicitly distinguishes from running the play via agree_playbook, and the phrase 'from an oversized agent activity' differentiates it from siblings like create_playbook. It 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 gives explicit guidance on when to use: 'Use when a run hit step/continuation limits because the work is multi-unit.' It also explains the next step (operator agrees via agree_playbook) and clarifies that this tool does not run the play. This is strong situational guidance that prevents misuse and guides the agent to the correct 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?

With no annotations provided, the description carries the full disclosure burden and delivers: it reveals that the code is 'inert until the code is shared', explains the security rationale for excluding automatic discounts, and discloses the sensitive-tier approval flow (manager approval on first use, from-now-on vs just-once modes). This exceeds typical descriptions for a mutation tool, though it could go further on write-scope details or Shopify-side 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 main purpose is front-loaded in the first sentence, followed by a crisp differentiator (why automatic discounts are excluded) and a one-line usage directive. The routing and sensitive-tier notes earn their place as they affect tool selection and invocation. Slightly verbose with the parentheticals, but every information chunk serves a functional purpose.

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

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

For a 5-param tool with no output schema and no annotations, this description is thorough: it covers the discount type, activation behavior, exclusions and reasons, routing, and approval requirements. It's complete enough for an agent to decide when to invoke it and what to expect. A minor gap is no mention of a return value (e.g., the created discount ID), but that's not a blocker given the rubric.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-level meaning beyond the schema (the only echo is the concept of the buyer-entered 'code' in the purpose sentence). The schema already documents each param well (e.g., format for code, bounds for percentage, ISO format for ends_at), so no penalty is warranted, but the description doesn't enrich semantics either.

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+scope: 'Create a CODE discount in the connected Shopify store (percentage off, applies when a buyer enters the code...)' It clearly distinguishes CODE discounts from automatic discounts, and the parenthetical explains exactly what the discount does and its behavior. This fully disambiguates it from sibling tools like list_shopify_discounts and create_shopify_product.

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 a clear use case ('Use for building promotions the operator will distribute') and an explicit when-not: 'Automatic discounts are deliberately not available here (they change every checkout unprompted and need approval).' The routing line 'Shopify: create a percentage discount CODE (never automatic discounts)' reinforces when to use it, though it never names a specific alternative sibling tool to use instead.

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 no annotations provided, the description carries the full burden of disclosure. It reveals that the page is created as an unpublished draft, never goes live without a separate approval step, and details the sensitive-tier approval behavior (manager approval needed, from-now-on vs just-once semantics). This goes beyond the schema and provides critical safety information.

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 and well-structured. It opens with the most important detail (unpublished draft), then usage, then a routing rule and approval note. Every sentence earns its place; there is no fluff or 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?

Given the absence of annotations and output schema, the description covers all necessary context: purpose, side effects (draft, not live), approval workflow, and when to use it. For a create operation, it provides sufficient context for an agent to safely invoke the tool.

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

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

Schema description coverage is 100% (all three parameters have descriptions), so the baseline is 3. The description mentions setting 'title and body HTML,' but this is already explicit in the schema. No additional parameter semantics, constraints, or examples are provided 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 explicitly states it 'create[s] a new page... as an UNPUBLISHED draft' and mentions setting title and body HTML, clearly identifying the verb and resource. It also differentiates from publishing by emphasizing 'never live' and that publishing is a separate step, distinguishing it from sibling tools like publish_shopify_page.

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 states when to use it: 'Use when a person or agent is building out site content.' It implies when not to use it (when live publishing is needed) but does not explicitly name alternatives such as publish_shopify_page or update_shopify_page_draft, so a clear when-not or alternative tool reference is missing.

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?

No annotations are provided, so the description carries the full burden. It prominently discloses the draft-only behavior, the approval-gated publishing process, and the sensitive-tier approval requirement. It lacks detail on error conditions or side effects (e.g., whether it overwrites existing products), but the key behavioral constraints are well covered.

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 composed of two clear paragraphs. The first is front-loaded with the key behavior (create draft, never live) and the fields set. The second paragraph includes routing and approval details — useful, but slightly redundant with the first paragraph's 'publishing is a separate approval-gated step' and the explicit routing line. Slight redundancy prevents 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?

This is a mutation tool with no output schema, but the description clearly states what it does (creates a draft product), what it doesn't do (publish), when to use it, and the approval implications. Given the 100% parameter schema coverage and clear behavioral transparency, the description is complete for an agent to decide and use the tool safely.

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

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

The input schema already provides 100% coverage of all six parameters with clear descriptions (e.g., 'Product title', 'Vendor/brand name'). The description adds the context that title, description, vendor, type, and tags are the fields set, but does not add semantics beyond the schema for parameters like companyId or description_html. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the tool creates a new product in Shopify as a DRAFT, explicitly noting it's never live and that publishing is a separate approval-gated step. It lists the fields it sets (title, description, vendor, type, tags), which distinguishes it from sibling tools like create_shopify_discount_code, create_shopify_page, update_shopify_product_draft, and publish_shopify_product.

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

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

The description explicitly states when to use the tool ('Use when building out the catalog') and what happens next ('the operator approves go-live later'). It also includes routing guidance ('Shopify: create a DRAFT product... never live') and notes the approval tier, providing clear context that differentiates it from publishing 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?

With no annotations, the description adds value by disclosing the write-tier approval process, informing the agent about potential approval requirements. However, it does not mention return values or side effects like what the tool returns after creation.

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 concise with two sentences, no wasted words. The approval note is front-loaded effectively.

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

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

Given the complexity (3 params, no output schema), the description is incomplete. It does not explain what the tool returns after creation, how to reference the new spreadsheet, or any usage constraints beyond the approval note.

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

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

Schema coverage is 100%, so the description adds no additional meaning beyond what the schema provides for parameters like 'title', 'headers', and 'companyId'. The 'optional headers' is already in 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 'Create' and the resource 'new Google Spreadsheet with optional headers', distinguishing it from siblings like 'create_google_doc' and 'append_to_sheet'.

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

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

The description implies usage for creating a new spreadsheet but lacks explicit when-to-use guidance compared to alternatives like 'update_sheet' or 'create_folder'. The approval note hints at context but does not compare 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?

With no annotations provided, the description carries the full burden. It discloses that the draft is created in PAUSED state and spends nothing, and it surfaces the sensitive-tier approval requirement (manager approval on first use, with options for just-once or from-now-on). It does not mention potential side effects like whether it overwrites existing drafts or what happens on failure, but the key safety and authorization behaviors are clearly stated.

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 paragraphs. The first sentence conveys the core purpose and state, and the second paragraph covers the approval nuance. It is front-loaded with the most important information and avoids redundancy, though the sensitive-tier note could be more compact. Overall, it is efficient and readable.

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 creates a campaign and line item, the description covers the active state (paused, no spend) and the approval step. It does not describe return values (no output schema exists), but that is not strictly required. The essential prerequisites like companyId and ad_account_id are documented in the schema. The description is sufficiently complete for an agent to call it correctly without ambiguity.

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% — every parameter has a description in the input schema. The description does not add extra meaning to the parameters; it only mentions 'campaign + line item' which loosely maps to campaign_name and objective, but that is already implied by the schema. Thus, 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 opens with a specific verb and resource: 'Create an X (Twitter) ads draft — campaign + line item'. It clearly states the scope (campaign + line item) and the crucial state (PAUSED, spending nothing). It also distinguishes itself from the sibling create_meta_ad_draft, so an agent can immediately tell this is the X-specific draft 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?

It explicitly says 'Use when the user wants to set up or draft an X ad' and clarifies that activation is a separate human-approved step via set_x_ad_status. It also notes that it is distinct from create_meta_ad_draft, directing the agent toward the right sibling for Meta ads. This gives 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?

No annotations exist, so the description carries full burden. It explains soft-delete (is_active=false), reactivation possibility, and the special case of Linnet. It also discloses the sensitive-tier approval requirement. Missing details about side effects on ongoing tasks 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?

The description is two sentences plus a note, no redundant information. It is front-loaded with the primary action and usage triggers, then behavioral details. 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 the simplicity of the tool (3 params, no output schema, no annotations), the description covers purpose, usage constraints, soft-delete behavior, and approval requirements. It could mention prerequisites (e.g., agent must be active) or error scenarios, but overall it is sufficiently complete for an agent.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description does not add extra meaning for parameters like 'reason' or 'agent_id'; it only reiterates behavior. Thus, baseline score of 3 is appropriate.

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

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

The description clearly states the action (deactivate/archive) and the resource (AI agent/specialist) with specific verbs. It distinguishes from sibling tools by listing user phrases like 'remove [agent]' and 'deactivate [agent]', making it easy for the agent to select this tool.

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

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

The description provides explicit usage triggers (user phrases) and a constraint ('Cannot deactivate Linnet'). It notes the soft-delete behavior and reactivation possibility. However, it does not explicitly list when not to use or suggest alternative tools for related tasks.

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 no annotations, the description carries the full burden, and it does well by warning that this 'initiates a multi-step agent process' and mentions trust scoring, autopilot evaluation, skill learning, and deliverable queue progression. It also explains the sensitive-tier permission nuance. It does not address reversibility or what is returned, keeping it below a 5.

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

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

The description is appropriately sized for a complex tool and front-loads the core action before side effects and usage rules. The bracketed authorization note is dense but relevant, though the sentence about 'trust scoring, autopilot evaluation, skill learning, and deliverable queue progression' could be tightened.

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 15 parameters, conditional class-specific actions, and no output schema, the description provides enough high-level context to make the tool's role and side effects clear, while the schema handles the parameter-level details. It does not mention how to list Command Center cards first or describe the return value, but these are minor gaps.

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

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

Schema description coverage is 100%, and each parameter already has detailed semantic descriptions. The tool description adds only high-level context for the split behavior, so it does not significantly expand on 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: 'Approve or deny a Command Center card,' and adds the split-card behavior, making the core function clear. It does not explicitly distinguish this from sibling tools like approve_pipeline_item or confirm_mcp_approval, so it stops short of a 5.

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

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

The bracketed note gives concrete usage context: company managers can run this without a card, other members need a one-time ask, and connector OAuth still requires the connect card. This provides a clear authorization boundary, though it does not name alternative tools explicitly.

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

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

No annotations exist, so description carries full burden. Explains exact side effects: deactivates reviewer agent, strips from pipelines, archives (not permanent delete). Includes sensitivity approval tier info.

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 paragraphs with front-loaded core action. Every sentence adds value; no waste. Efficiently includes triggers, side effects, and approval 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?

Despite no output schema, description covers all relevant context: what gets destroyed (agent, pipeline associations), archiving behavior, and approval requirements. Complete for a complex deletion 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%; parameters are well-described in schema. Description adds minimal extra meaning beyond referencing 'icp_id from get_icps response' and 'companyId' as required. 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 tool deletes an ICP, with specific verb ('delete') and resource ('Ideal Customer Profile'). Distinguishes from other tools by specifying it mirrors the UI's delete action and involves deactivation, stripping, and archiving.

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 user triggers: 'delete this ICP', 'remove this customer profile', 'get rid of this persona'. Includes sensitivity/approval context but does not list alternatives or when-not-to-use explicitly.

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

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

Without annotations, the description should disclose destructive nature and consequences. It only mentions 'delete' and the approval process, but not irreversibility or impact on associated data.

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

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

Two concise sentences. The first states purpose, the second adds a behavioral note. No wasted words, though the approval note could be more compact.

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?

Provides identification methods and a behavioral note, but lacks details on return values, error conditions, or prerequisites. Adequate but not comprehensive.

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

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

Schema coverage is 100%, baseline is 3. The description adds a minor clarification about identification methods (content snippet, ID, 'newest'/'latest') but does not significantly extend schema meaning.

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 action 'Delete' and the resource 'idea from Ideas', which is clear and specific. It distinguishes from siblings like 'capture_idea' (create) and 'triage_idea' (categorize).

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

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

No guidance on when to use this tool versus alternatives like 'capture_idea' or 'triage_idea'. The approval note is useful but does not address usage context or exclusions.

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

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

Discloses safe delete (recoverable), disambiguation refusal, and write-tier approval system. No side effects mentioned, but covers key behavioral traits without annotations.

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

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

Two concise paragraphs, front-loaded with core functionality. No unnecessary words.

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

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

Covers action, identification, disambiguation, and approvals. Lacks return value info, but no output schema makes it sufficient.

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

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

Schema has 100% coverage; description adds identification guidance and disambiguation context, going 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?

Clearly specifies the tool archives a key result (safe delete, recoverable). Distinguishes from siblings like update_key_result and delete_objective by using 'archive' and 'recoverable'.

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 identification methods (title or ID) and disambiguation behavior. Lacks direct comparison to sibling tools (e.g., when to use update_key_result instead), but context is sufficient.

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

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

With no annotations provided, the description carries full burden. It transparently discloses the soft-delete behavior (archive, moved to _archived/, restorable), the required parameters (slug, companyId), and the write-tier approval requirement via the bracketed note. This fully informs the agent of the tool's effects and constraints.

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

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

The description is concise at two primary sentences plus a separate bracketed note on approval. The key behavior is front-loaded, but the note slightly disrupts flow. Still, it is efficient with no superfluous 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?

The description explains the mutation behavior well but lacks information about the return value or success confirmation. Given no output schema, the agent would infer a success message, but explicit mention could reduce ambiguity. Coverage is adequate but not exhaustive.

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 does not add meaning beyond the schema: it mentions 'by slug' and 'companyId', but the schema already describes these. No additional semantic details like slug format or validation are provided.

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 archives (soft deletes) a knowledge file by slug, specifying the move to _archived/ and that it can be restored later. This distinguishes it from sibling tools like update_knowledge_section or share_knowledge, as it is the only tool for deletion.

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

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

It explicitly says 'Use when the user explicitly asks to remove a knowledge document,' providing clear context for invocation. However, it does not mention when not to use this tool or any alternatives, such as using update_knowledge_section for deprecation, which would strengthen 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?

Given no annotations, the description carries full burden. It discloses that deletion is safe and recoverable (never hard-deleted), and explains the refusal behavior on title ambiguity. It does not mention whether archiving is reversible or what the return value looks like, but these are minor gaps.

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 paragraphs, frontloaded with purpose, then behavioral notes. Every sentence adds unique information without redundancy. Efficient and structured.

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

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

With no output schema, the description covers purpose, disambiguation, recovery, and approval. It lacks detail on return value or error cases, but for a three-parameter tool with 100% schema coverage, this is reasonably 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?

Input schema coverage is 100%, but the description adds value by stating that title is preferred and explaining how disambiguation affects ID usage. This goes beyond the schema alone.

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 archives (soft deletes) an objective and its key results, distinguishing it from hard deletion. It also explains the disambiguation mechanism when multiple objectives match a title, which differentiates it from similar sibling tools like delete_key_result.

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

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

The description provides guidance on when to use title vs ID, including disambiguation. It also mentions the write-tier approval process. However, it could explicitly contrast this tool with delete_key_result or delete_idea to clarify scope.

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?

No annotations provided, but the description transparently explains the asynchronous behavior: 'first call returns a run_id immediately; call deliberate again... after ~1-2 minutes to fetch the result.' It also describes the multi-round argument process, adding value beyond the schema.

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

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

The description is somewhat lengthy but well-organized: purpose, usage, async flow, routing. It front-loads the key action and is structured with clear sentences. A minor reduction could improve conciseness, but it remains 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?