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?

No annotations are provided, so the description carries full burden. It discloses that the addition does not regenerate the whole plan and mentions the approval sensitivity (first use may require manager approval, etc.). However, it does not describe what happens to existing activities, whether the operation is idempotent, or any potential side effects. Still, the core behavioral traits are adequately 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 exceptionally concise, consisting of two sentences plus a parenthetical note about approvals. It front-loads the primary purpose and usage guidance without any wasted words. Every sentence adds value, making it efficient for an AI agent to parse.

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 (nested object with many fields, no output schema, no annotations), the description provides the essential purpose and usage guidance. It does not explain the return value or confirmation behavior, nor does it mention prerequisites like agent existence. However, the sibling tool differentiation and approval caveat partially compensate. The input schema is comprehensive, so the description is reasonably complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add any extra meaning to the parameters beyond what the schema already provides. The schema itself is detailed with descriptions for each subfield of the activity object. The description's only contribution is implying that 'activity' is a single activity, which is already clear from the tool name and context.

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

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

The description clearly states the verb 'Add' and the resource 'activity to an agent's activity plan', specifying it adds exactly one activity without regenerating the whole plan. It distinguishes itself from the sibling tool 'recalibrate_agent_jd' by explaining the alternative use case (rebuilding the entire plan). This gives a specific, unambiguous purpose.

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

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

The description explicitly tells when to use this tool ('give an agent a new recurring or one-off deliverable') and when to use the alternative ('To rebuild the entire plan, use recalibrate_agent_jd...'). It also includes a sensitive-tier note about manager approval requirements, providing clear context for usage.

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

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

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?

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?

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 provided, the description carries the full burden. It discloses that the tool is receive-only, reads only the user's own mailbox, and returns specific fields (sender, subject, safe text snippet, OTP codes, login links). It also mentions the sensitive-tier approval requirement. It does not cover error scenarios or rate limits, 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 front-loads the core purpose and return values in the first sentence, then adds approval context in a separate paragraph. Every sentence adds value without unnecessary 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 simple nature of a read-only inbox checker, the description covers the return format (sender, subject, snippet, OTP, links) and the approval requirement. It does not mention error conditions (e.g., empty inbox, invalid companyId), but the schema covers the required parameter. Overall, it is sufficiently complete for the tool's purpose.

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

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

The input schema has 100% description coverage for all 4 parameters, so the schema itself documents each parameter. The description does not add new parameter details but provides context for when parameters like since_minutes and from_domain are relevant. Based on the guidelines, a baseline of 3 is appropriate since the description does not significantly augment 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 that the tool checks the user's own agent email inbox for messages sent to their @agents.getfreedomos.com address. It specifies it is receive-only and returns recent unread messages. While it does not explicitly differentiate from the sibling tool list_inbox, it adds context by emphasizing 'reads only YOUR mailbox', which helps distinguish its scope.

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: 'Use when a login, sign-in, or verification flow tells you it emailed a one-time code or magic link to your agent address and you need to retrieve it.' This is clear and contextual. It does not mention alternatives or when not to use, but 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 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, the description carries full burden. It explains the polling mechanism, that it does not type into UI, and mentions write-tier approval. It could add more about persistence or side effects, but is fairly 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 around 100 words, front-loaded with core function, then nuance, then usage triggers. Every sentence adds value; no waste.

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

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

For a tool with 6 params and no output schema, the description covers purpose, mechanism, usage, and parameter examples. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing usage examples for target_session_id and instruction constraints (imperative, 1-4000 chars), going beyond schema.

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

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

The description clearly states the tool queues instructions for external sessions (Grok, Claude Code) and distinguishes it from direct UI interaction. It uses specific verbs and resource, and the unique purpose differentiates it from siblings.

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

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

The description explicitly tells when to use (e.g., 'tell Grok…') and clarifies a limitation (does not type into UI). It lacks explicit alternatives but provides strong 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 carries the burden. It discloses the write-tier and approval requirement, indicating mutability and access constraints. It does not contradict any annotations (none 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 sentences plus a concise approval note. Every sentence adds value: purpose, context, and behavioral note. Front-loaded with key information.

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

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

Given 10 parameters and no output schema, the description covers high-level usage and key behavioral aspects (approval). It does not detail return values or side effects but is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining measurable outcomes, tracking progress, and how to identify the parent objective. It also clarifies measure_source as auto-updating.

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 'Add' and resource 'key result' (KR) with clear OKR context. It distinguishes from siblings like 'update_key_result' and 'delete_key_result' by specifying the action of creating a new KR.

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

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

The description explains when to use the tool (adding a KR to an objective) and how to identify the parent objective by title or ID. It includes an approval note but lacks explicit when-not-to-use guidance or 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 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, 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 burden. It transparently reveals that this is a draft action (not execution), requires operator agreement, and includes a sensitive-tier approval process. However, it does not disclose potential side effects (e.g., whether the original activity is modified or whether a persistent record is created) or the return format.

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 efficiently structured: a clear first sentence, a usage condition, and a concise approval note. All sentences earn their place and the front-loading is good. The approval note is slightly verbose but provides valuable context.

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

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

For a complex tool with 11 parameters, no output schema, and no annotations, the description covers the 'when' and 'why' but leaves major gaps: parameter semantics, post-draft process, persistence, and what happens next. It is incomplete for an agent to safely invoke the tool without further schema details.

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

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

Schema coverage is low (36%) with 7 undocumented parameters. The description does not compensate by explaining any parameter names or their roles. It only alludes to 'steps' and 'human review' conceptually, but does not map them to draft_steps or other fields. Users cannot infer the meaning of reason, linked_kr_id, or draft_custom_instructions from the 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 'Draft a Play' with a specific resource (growth_tactics with steps + human review) and source (oversized agent activity). It also clarifies that it does not run the play, which distinguishes it from execution tools. However, it does not explicitly name sibling tools like split_agent_activity or run_tactic for comparison.

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

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

The description gives an explicit use case: 'Use when a run hit step/continuation limits because the work is multi-unit.' It also states the workflow expectation (operator Agrees on Focus first) and that the tool only drafts, not executes. It does not mention alternatives or exclusions, 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, 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?

Since no annotations are provided, the description carries the full burden. It discloses the approval behavior (first use may require manager approval, from-now-on vs just-once approval), which is helpful for understanding side effects and access restrictions. No other behavioral aspects like idempotency are mentioned, but this is acceptable given the context.

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

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

The description is extremely concise: two sentences plus a parenthetical note about approval. Every sentence adds value, with no filler. The approval note is appropriately placed after the main 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 8 parameters, 3 required, and no output schema, the description provides sufficient context on the tool's purpose and a key behavioral aspect (approval). It does not explain the return value, but that is partially mitigated by the absence of an output schema. The description is complete enough for an agent to invoke correctly.

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

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

The input schema has 100% description coverage, so the schema itself clearly documents each parameter's meaning and constraints (e.g., enum values, fallback behavior for linked_kr_id). The tool description adds no additional parameter information beyond restating the tool's purpose. 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 verb 'create' and resource 'tactic', specifying 'a new growth tactic for the company'. It differentiates from siblings like 'update_tactic', 'delete_tactic', and 'generate_tactics' by indicating this is for adding a tactic manually.

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 user wants to add a tactic, strategy, or action item.' It also mentions the approval requirement for first use, which guides the agent on when manual approval may be needed. However, it does not explicitly contrast with 'generate_tactics' for AI-generated tactics, leaving some 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?

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?

No annotations are present, so the description carries the disclosure burden. It does disclose the sensitive-tier nature, multi-step agent process, first-use manager approval, and the full approval pipeline. However, it does not detail all side effects, such as the creation of a product-request card for splits or the non-resolving nature of 'dismissed'/'snoozed' decisions.

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 main action and includes useful behavioral notes. The bracketed approval note feels a bit like structured metadata, but overall the description is concise and every sentence adds information without excessive padding.

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

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

Given the tool's complexity (10 parameters, multiple decision types, split mode) and the absence of annotations or output schema, the description is not fully complete. It fails to mention the snoozed/dismissed decisions and the capability-approval card type referenced by grant_mode, though the rich parameter schemas fill many 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%, so the parameter descriptions in the schema are already thorough. The main description adds little parameter-level meaning beyond mentioning the split concept, so the baseline score of 3 applies; the description does not compensate 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 core action ('Approve or deny a Command Center card') and distinguishes it from read-only siblings like get_command_center_item. However, it omits two valid decisions (snoozed, dismissed) that the schema includes, making the purpose slightly incomplete.

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 this tool is used (Command Center decisions) and mentions the split capability. But it does not explicitly compare with related tools like approve_pipeline_item or confirm_mcp_approval, nor does it state when not to use it, so it lacks explicit 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?

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?

With no annotations, the description carries the full burden. It discloses the operation is 'safe delete - recoverable', implying non-destructive behavior. It also mentions write-tier approval requirements. However, it fails to specify what 'archiving' entails (e.g., visibility change, data retention period), required permissions, side effects on related data (e.g., associated commitments), or the return value.

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 consists of two short sentences and a concise write-tier note. Every sentence adds value: purpose, alternative identification method, and approval behavior. No filler 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?

The description covers purpose and parameter hint, but given no output schema, it is missing information about return values (e.g., success confirmation) and recovery behavior (how long recoverable?). The write-tier note partially compensates, but overall leaves gaps for a deletion operation.

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

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

Schema coverage is 100% (all 3 parameters documented in schema). The description adds a hint about using title instead of ID, but this is already implied by the parameter description. The added value is minimal, 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 action ('Archive a tactic') and the resource ('tactic'). It distinguishes this from siblings like 'delete_icp' or 'delete_idea' by specifying it applies to tactics. The phrase 'safe delete - recoverable' adds important nuance about the operation's nature.

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 'Can identify by title instead of ID', advising on how to use parameters. The write-tier note explains the approval model (first use may require approval, persistent approval makes future calls seamless). It does not include when not to use or alternatives, but provides clear context for usage.

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

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

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?

Given the complexity (async, multiple parameters, no output schema), the description covers the core flow, parameter usage, and rationale. Some details like error handling or maximum wait times are missing, but overall it's sufficiently complete for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for parameters, e.g., 'Omit question/positions when polling', 'The more context, the better the arguments', and required conditions. This adds meaningful guidance beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Run an adversarial deliberation on a decision.' It uses a specific verb and resource, and the adversarial deliberation concept is unique among siblings, distinguishing it effectively.

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 advises 'Use for important decisions where you want to stress-test options from multiple angles.' It includes a routing note: 'Important decision → deliberate for adversarial analysis.' While it doesn't explicitly mention when not to use, context is clear enough.

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

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

No annotations provided, so description carries full burden. It states 'Read-only; never executes or sends code', 'writes NOTHING', details the draft-then-ratify workflow, and explains the sensitive-tier approval process. This is comprehensive behavioral disclosure.

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

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

Description is front-loaded with core functionality, followed by routing and approval notes. It could be slightly more concise, but the structure is logical and each part adds value. No redundant statements.

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 fully explains the tool's behavior: scanning code, drafting features with citations, limits, read-only, dependency on repo connection, and the ratification flow. It also covers the error case and authorization notes. Very complete for a tool of this 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?

Only one parameter 'companyId' with 100% schema description coverage. The description does not add meaning beyond the schema's existing description of the parameter. Baseline 3 is appropriate as the schema already documents it sufficiently.

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

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

Description clearly states the tool scans source code and drafts a capability list of features with file citations and limits. It explicitly says 'read-only' and distinguishes itself from manual typing or website scraping via the routing condition. The purpose is specific and distinct from siblings like 'derive_from_website' and 'ratify_capability'.

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?

Description provides clear when-to-use guidance: 'Use to populate or refresh a software product's capabilities without hand-maintaining them' and a routing condition. It also mentions prerequisites (repo must be connected) and handles the case where it's not. However, it does not explicitly list alternatives or when not to use this tool.

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

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

No annotations provided, so description carries full burden. It discloses that nothing is persisted, notes sensitivity and approval requirements, and labels itself as a 'SPIKE tool'. Still lacks some details like rate limits or error handling, but provides key behavioral context.

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

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

The description is longer than ideal, containing a spike tool label, output details, persistence statement, usage guidance, and a sensitivity note. While structured, it could be more concise by reducing redundancy (e.g., multiple references to 'spike').

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

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

No output schema, but description explains return: ICP, brand voice, 3 drafts. Covers persistence and approval. Missing details on error handling or URL validation, but sufficient for understanding the tool's primary behavior.

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

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

Schema coverage is 100%, so baseline 3. The description adds context for url (must include https/http, suggests homepage or About page) and for companyId (required for company-scoped tools). This goes beyond the schema's brief descriptions.

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

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

The description clearly states it reads a business URL and returns a derived ICP, brand voice, and 3 drafts. This is a specific verb+resource+output, differentiating it from sibling tools like browse_url that only read a page without analysis.

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

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

Explicitly says to use when the operator asks to run the website-derivation spike against a real URL to show what can be seen about the business. However, it does not include when-not-to-use or explicitly mention alternatives, though the 'spike' nature implies limited production 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?

With no annotations, the description carries full burden. It discloses that drafts are written to lead_drafts as pending_review, returns IDs+previews, and mentions the write-tier approval requirement. But it lacks details on side effects, idempotency, or error conditions.

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

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

The description is concise, front-loaded with the core action, and no wasted words. The second paragraph adds important behavioral context efficiently.

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

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

For a 12-parameter tool with no output schema, the description covers purpose, usage context, tone, variant details, and approval requirement. It could be more complete by explaining failure modes or relationship to other tools beyond synthesis.

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 parameter-level detail beyond the schema; it focuses on overall tool behavior.

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

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

The description clearly states the tool produces two outreach draft variants (A/B) for a lead given an angle, specifying the resource, action, and output. It distinguishes from sibling tools like synthesize_lead_hypothesis and send_lead_draft.

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 advises using this tool after synthesize_lead_hypothesis, providing clear context. However, it does not mention when not to use or list alternatives beyond this sequence.

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 discloses behavior: it drafts from the website, returns a draft with evidence and confidence, writes nothing, requires operator confirmation, and mentions the sensitive-tier approval process. It also states the agent is a mirror not an author, ensuring correct expectations.

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

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

The description is concise and well-structured: first paragraph explains core behavior and use case, second paragraph provides important security context. Every sentence serves a purpose with no redundancy.

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

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

Despite no output schema, the description effectively communicates the return value (DRAFT proposal with evidence and confidence), the ratification workflow, and the approval tier. This is sufficient for an agent to understand and use the tool correctly.

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

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

The input schema has 100% description coverage, so the description adds minimal value beyond restating the tenet enum and companyId requirement. No examples, constraints, or additional context 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 drafts a company tenet (mission or vision) from the company's existing website. The verb 'draft' and resource 'tenet' are specific, and the description distinguishes it from simply creating or updating a tenet directly by emphasizing it's a draft for ratification.

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 'Use when a tenet is empty but the company already exists (has a website).' Provides context that it avoids blank fields and returns a draft for operator confirmation. Lacks explicit mention of when not to use or alternative tools, but the guidance is clear enough.

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

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

With no annotations provided, the description carries full burden. It discloses that text is rendered as real legible text (differentiator), that it only produces artifacts requiring separate publishing via send_to_user, and mentions an approval gate (write-tier). It does not cover side effects or destructive behavior, but the description adds useful 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 fairly long but front-loaded with the core purpose. It uses bullet points for routing and approval info, which aids readability. Slight redundancy in the routing section could be trimmed, but overall it is well-organized.

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 (8 parameters, no output schema), the description explains input semantics well but lacks details about output format (e.g., artifact type, how to access the generated carousel/PDF). The absence of output schema makes this gap more significant.

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 meaning: for slides it gives ideal range (3-8, max 12), for citation it specifies 'GENUINE external source ONLY' and warns against prefixing with 'Source:', for accent_hex it says to pass tenant's brand color, and for brand_label it says pass your company's label only. These details go well beyond the schema descriptions.

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

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

The description clearly states the tool renders a multi-slide image carousel and LinkedIn-PDF from structured slide copy, emphasizing legible text which distinguishes it from AI image/video tools that produce garbled text. It also specifies use cases (value-demonstration B2B content) and routing, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool (carousel/slide deck/PDF/legible cited-answer overlay) and includes a routing hint. However, it does not explicitly list alternative tools or conditions when not to use it, though the context implies differentiation from other image generation 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 exist, so the description carries full responsibility. It discloses default behavior (Quality Mode, highest live API fidelity), capability boundaries (max 3 refs, 1K/2K), and operational caveats (first use may require manager approval, approval type implications). It also explains the model_tier tradeoff and routing priority, offering rich behavioral context well 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 long but densely packed with useful information. It opens with the core function, then lists capabilities, routing, and approval notes. Each section earns its place, though some redundancy with the schema exists (e.g., 'Use model_tier=standard only for cheap drafts' mirrors schema text). Overall well-structured and 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?

With 12 parameters, no output schema, and no annotations, the description covers the key behavioral aspects: generation/edit, quality/resolution, multi-ref limits, routing, and approval workflow. It omits some details like return values or save_to_drive behavior, but these are covered in the schema. Given the tool's complexity, the description is sufficiently complete for an agent to use it confidently.

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

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

Schema coverage is 100%, and schema descriptions already explain most parameters with detail. The description adds value by clarifying the meaning of model_tier in context ('Quality Mode default — highest live API fidelity; closest to consumer Image 2.0') and reinforcing the multi-ref composite pattern via artifact_ids. It doesn't reinvent parameter semantics but enriches the selection rationale.

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: 'Generate or EDIT an image using xAI Imagine.' It enumerates supported styles (photorealistic, illustrations, flat graphics, icons, banners), resolutions (1K/2K), and editing capabilities (single or multi-image edit with ≤3 refs). It explicitly designates itself as the routing hub for ALL image generation and editing, distinguishing it from siblings like generate_vector_image and generate_video.

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 routing: 'ALL image generation and editing → use this (2 credits).' It also gives conditional guidance: 'Use model_tier=standard only for cheap drafts' and warns about the sensitive-tier approval requirement. This tells the agent when to choose this tool and how to adjust parameters based on use case.

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

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

No annotations are present, so the description carries full weight. It discloses that it uses company data, returns suggestions, and includes an important behavioral note about write-tier approval requirements (first use may require manager approval, with options for ongoing or one-time approval). There is no contradiction with annotations.

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

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

The description is concise, with two clear paragraphs: the first explains the tool's functionality and value, the second provides behavioral notes. No unnecessary words, though the approval note could be slightly 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?

Given no output schema, the description adequately explains the return (suggestions for use with create_key_result) and the input context (mission, vision, financials, existing KRs). It covers main aspects but lacks details on edge cases or limitations.

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

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

Schema coverage is 100% with each parameter described. The description reiterates that suggestions are generated for an objective (matching objective_id/objective_title) but adds no new parameter-level details beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly specifies the verb 'Generate' and the resource 'key result suggestions for an objective', and distinguishes itself from sibling tools like 'create_key_result' by stating it returns suggestions that can then be created. It also details the context used (mission, vision, financials, existing KRs).

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

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

It provides a clear workflow: generate suggestions then use create_key_result. However, it does not explicitly state when not to use this tool or compare to alternatives like get_okrs or update_key_result, which would improve 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 full burden. It discloses the write-tier approval behavior and persistence, but does not detail side effects, error handling, or idempotency. This is 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 concise, with two short paragraphs. The first paragraph clearly states the purpose, and the second adds practical approval context. There is no redundancy or 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 tool's complexity (6 parameters, no output schema), the description covers generation, saving, optional bindings, and approval. It lacks return value details but is otherwise sufficient for an agent to understand the tool's function.

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 additional meaning beyond the schema for parameters like userPrompt, category, etc. It merely restates the enum categories.

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 (generate and save), the resource (growth tactics), and the constraints (5 grounded tactics for a 4-F category). It distinguishes from sibling 'create_tactic' by specifying batch generation and persistence.

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 tells when to use ('when an agent should author concrete tactics for a goal — not just brainstorm') and provides context with write-tier approval notes. However, it does not explicitly mention when not to use or name alternatives.