freedom-mcp

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

The annotations include idempotentHint=false, but the description directly says 'Idempotent on already-acked → not found.' This directly contradicts the idempotentHint annotation, which is a serious inconsistency. The approval-tier note adds useful context, but the contradiction caps the score at 1.

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

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

The description is front-loaded with purpose and usage conditions, and every sentence adds operational value, including the approval-flow note. It is somewhat dense and jargon-heavy, but not padded or redundant enough to lose more than one point.

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

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

For a simple one-required-parameter mutation with no output schema, the description covers the triggering condition, approval behavior, and the already-acked case. The idempotency contradiction undermines completeness, and success-return behavior is not described, so it is adequate but not fully complete.

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

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

The input schema covers 100% of parameters with clear descriptions (UUID source and companyId membership requirement). The tool description itself adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Mark a pending attention directive as acked after the host session has taken the instruction.' It also adds a distinguishing scoping condition, 'for the same operator who owns the queue,' which separates acknowledgment from creating, listing, or canceling directives.

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

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

It explicitly states when to use the tool: after the host builder has executed or deliberately skipped a polled directive, and only for the same operator who owns the queue. However, it does not name an alternative tool for the opposite case, so it falls just short of a fully explicit when-not/alternatives statement.

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

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

Adds meaningful behavioral context beyond annotations by explaining the write-tier approval behavior, the from-now-on vs just-once distinction, and the 'card is the yes' rule. It does not directly elaborate on destructiveHint=true, but it also does not contradict the annotation because adding to a live plan can still alter schedule state.

Agents need to know what a tool does to the 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 tightly written and front-loaded: the core action and scope come first, the alternative comes second, and the approval instruction earns its place. There is no filler or repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 nested-object mutation tool with no output schema, the description plus schema covers selection, parameters, scope, and permission behavior well. A brief statement about the expected result or returned confirmation would fully close the loop, but nothing essential is missing 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 the detailed parameter documentation carries the semantic burden. The description reinforces plan-level intent but does not add per-parameter meaning beyond what the schema already provides, matching the baseline for high coverage.

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

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

States a specific verb and resource: 'Add ONE activity to an agent's activity plan'. It also explicitly distinguishes this from regenerating the whole plan, which separates it clearly from sibling tools like recalibrate_agent_jd and update_agent_activity.

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

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

Gives direct usage guidance: use it to add a new recurring or one-off deliverable, and names the exact alternative (recalibrate_agent_jd with regenerate_activities=true) for rebuilding the plan. The approval note also tells the agent when to call and not to re-ask, making the invocation protocol explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the write nature is known. The description adds valuable behavioral context: approval requirements ('first use may require a manager's approval'), the 'card is the yes — do not re-ask' behavior, and the recurring-tag convention that complete_commitment reads. It doesn't contradict annotations. A small gap: it doesn't explicitly state what happens on approval denial, but the approval behavior is well covered.

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

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

The description is dense but well-organized: purpose first, then usage triggers, then pairing guidance, then approval behavior. Every sentence earns its place, though the approval note is a bit long and could be tightened. The front-loading of 'ALWAYS use this (not save_knowledge)' is effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6-param write tool with no output schema, the description covers the key decision points: when to use, how to handle event dates, how to mark recurring commitments, and approval behavior. It doesn't explain return values, but there's no output schema and the 'card is the yes' hints at the result. Minor gaps: no explicit mention of what happens if the user is ambiguous about the prep deadline, but the 'confirm with the user' instruction covers it.

Complex tools with many parameters or behaviors need more documentation. 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 6 parameters. The description adds meaningful semantic value beyond the schema: it explains the due_date prep-deadline reframing for events (default ~7 days before, store actual date in description), the recurring-tag convention for description, and the domain field's scope. This goes beyond baseline 3 by clarifying non-obvious parameter 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 states a specific verb and resource ('Track a personal commitment, deadline, birthday, appointment, or obligation') and explicitly distinguishes it from save_knowledge by listing concrete triggers (birthdays, due dates, deadlines, tax filings, events to plan, gifts to send). This makes the tool's purpose unmistakable and 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 says 'ALWAYS use this (not save_knowledge) when the user mentions...' and provides a list of examples. It also gives guidance on pairing with save_knowledge for supporting context, and explains approval behavior ('call it on the first clear ask; the card is the yes — do not re-ask in chat'). This is exemplary usage guidance.

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

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

Annotations already mark readOnly=false and destructiveHint=true, so the write/mutation profile is known. The description adds valuable non-obvious behavioral context: the evidence-ranking rule, the write-tier approval requirement, and the instruction to treat the approval card as the yes without re-asking. No statement contradicts the annotations.

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

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

The description is front-loaded with the core operation and scope, then provides selection rules, exclusion, and approval behavior in a compact, bracketed note. Every sentence carries operational value; there is no filler or repetition of schema field definitions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an 11-parameter mutation tool, the description covers the high-level purpose, input acceptance criteria, exclusions, evidence ranking, and approval workflow; the schema covers parameter semantics. No critical usage gap remains for an agent to call it correctly.

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

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

Schema coverage is 100%, and the schema already defines each parameter, including the class enum and its rank weights. The description mostly recaps the evidence categories rather than adding new parameter-specific meaning, so the baseline 3 applies.

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

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

The description states a specific action and resource: 'Store one piece of REAL Customer Evidence for this company,' and enumerates accepted evidence types. It explicitly distinguishes itself from create_icp by saying it is NOT for inventing personas, so an agent can differentiate it from that sibling.

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

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

It gives explicit when-to-use conditions ('Use when the operator pastes a real customer quote, a call note, a review, or a provenanced usage signal') and an explicit when-not-to-use rule with the alternative ('NOT for inventing personas (use Customer Hunter / create_icp for hypotheses)'). It also instructs the agent on approval handling: call on first clear ask, do not re-ask in chat.

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

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

Annotations include destructiveHint: true, implying mutation, but the description adds significant detail: idempotency on (company, email), auto-triaging behavior, and write-tier approval requirements. This goes beyond what annotations provide, clarifying the operational impact and approval flow.

Agents need to know what a tool does to the 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 a clear first sentence stating purpose, followed by key constraints. It front-loads the primary action and then provides routing and approval context. It is a bit dense but every sentence earns its place, except perhaps the approval paragraph could be more streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 what the tool does, when to use it, key behavioral traits (idempotency, auto-triage), and approval requirements. With no output schema, it doesn't explain return values, but for a simple creation tool this is fine. It could mention typical success/failure responses, but it's not critical.

Complex tools with many parameters or behaviors need more documentation. 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 adds value by emphasizing that email or name is required (though not structural), and notes that source defaults to 'manual' which is already in the schema. No additional parameter semantics are needed beyond the schema.

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

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

The description clearly states it adds a new lead to the Leads CRM, specifying the table (crm_leads) and its integration with the Leads tab, triage, and outreach. It distinguishes itself from siblings like update_lead by focusing on creation, and from list_leads by being a write operation.

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

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

The 'Routing: CRM/sales → add a lead or prospect → use this' line explicitly tells the agent when to use this tool. It also provides guidance on idempotency and required fields (email or name), which helps the agent know when to call it. It does not explicitly name alternatives, but the routing context is strong.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context beyond that: every call creates an approval card, sends exactly once on approve, requires per-call manager approval, and has no standing grant. The 'do not re-ask in chat' note is particularly useful operational guidance.

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

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

The description is dense but well-structured: the core action is front-loaded, followed by requirements, exclusions, routing, and sensitive-tier guidance. Every sentence adds operational value, and the formatting makes the approval behavior and routing easy to scan.

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

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

For a mutation tool with no output schema, this description is remarkably complete: it covers the action, prerequisites, required and optional fields, approval behavior, exactly-once sending, exclusions, and sibling-tool routing. An agent has everything needed to invoke it 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 already has 100% coverage, clearly describing email, role, name, and companyId. The description reinforces the required/optional split and role presets ('team / manager'), but does not add significant new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb and resource: 'Add one human teammate to the current company by email.' It also differentiates itself from sibling tools by explicitly routing AI agents to interview_for_hire and existing member checks to 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?

The description says exactly when to use this tool ('not yet on get_team_members'), names the alternative for AI agents (interview_for_hire), and gives exclusions such as 'No bulk' and 'No permission designer.' It also explains the approval workflow and when to invoke the tool, leaving no ambiguity about routing.

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

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

The description discloses important behavioral context beyond annotations: it flags a 'sensitive-tier' approval flow ('first use may require a manager's approval...') and instructs on how to handle approval ('the card is the yes — do not re-ask in chat'). It also clarifies the operational scope versus storefront content. This adds value beyond the destructiveHint and readOnlyHint 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 front-loaded with the core action, followed by usage context, a boundary note, routing, and approval instructions. Each section serves a purpose, but the 'Routing' line largely repeats the first sentence, and the sensitive-tier note is somewhat lengthy. Overall it's well-organized and structured with parentheses and brackets, though slightly redundant.

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

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

For a mutation tool with no output schema, the description covers the core purpose, when to use it, what it does not affect, and the approval procedure. It does not mention return values, error handling, or failure modes, but these are often not critical for action tools. The completeness is strong given the schema and annotations already present.

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

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

Schema description coverage is 100% — all parameters (variant_id, delta, reason, companyId) are individually documented in the schema. The description's mention of '+/-' and 'stocked location' aligns with the delta parameter but adds no new field-level semantics that aren't already present. The baseline of 3 is appropriate.

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

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

The description states a specific verb ('Adjust'), a clear resource ('a variant's available inventory'), and the method ('by a delta (+/-) at its stocked location'). It also clarifies what it is not ('stock level is operational state, not storefront copy/price'), which differentiates it from price/content-related siblings. This is a precise, unambiguous 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 lists use cases: 'receiving stock, correcting counts, or reserving units.' It also provides a boundary note about not affecting storefront copy/price; however, it does not name specific alternative tools or provide an explicit 'when not to use' exclusion. The routing line reinforces the use case but doesn't mention alternatives by name.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=falseapper, but the description adds valuable behavioral detail: the approval workflow ('first use may require a manager's approval; a from-now-on approval makes future calls seamless, a just-once approval re-asks next time') and an explicit instruction to the agent ('call it on the first clear ask; the card is the yes — do not re-ask in chat'). This goes well beyond the annotations.

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

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

The description is front-loaded with the core action and consequences. However, it includes some cryptic extras like 'Operator door — Chat or MCP' and 'Same seal Focus writes' that may not be immediately meaningful, and the routing line slightly repeats the first paragraph. Still, each sentence adds useful 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?

The description covers the purpose, the prerequisite for run_playbook, the approval flow, and the relationship to get_playbook. Since there is no output schema, return semantics are not required. Minor gaps like clarifying the 'Operator door' phrase mean it's not perfect, 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?

The schema description coverage is 100%, so all parameters are already fully documented in the schema. The description does not add any additional parameter semantics beyond what is in the schema, so it stays at 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 the action ('Seal a Playbook plan'), the underlying field it sets (source_details.plan_agreed_at), and the consequence (so run_playbook can dispatch). It distinguishes itself from siblings like run_playbook by positioning itself as a prerequisite, and mentions get_playbook as the preceding step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides when-to-use guidance: 'Use after get_playbook when the steps look right' and a routing rule 'Agree who does what on a Playbook → use this, then run_playbook'. It also notes that Structured Plays refuse Run until this seal exists, which gives a clear precondition.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable behavioral context beyond annotations: the write-tier approval flow (manager approval, from-now-on vs just-once), the re-injection behavior at next voice mint, and the constraint that faith content stays operator-authored. It doesn't fully detail what 'settleable' means or the exact re-injection mechanics, but it adds substantial context beyond the annotations.

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

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

The description is well-structured with the core purpose and usage in the first sentence, followed by content guidance, then the approval flow. It's slightly dense with the bracketed write-tier section, but every sentence earns its place. The front-loading of the primary purpose and the clear separation of the approval caveat make it easy 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?

For a write tool with no output schema, the description covers the key operational details: when to use, what to write, length limits, approval flow, and re-injection behavior. It doesn't explain the return value or error cases, but the absence of an output schema lowers that burden. The main gap is not fully defining 'settleable' or the exact mechanics of 'open + settled_keep', but these are domain-specific terms that may be understood from context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context for the 'lesson' parameter by specifying content guidance ('what worked, what failed, which principle') and length constraint ('Short notes only'), which complements the schema's example. However, it doesn't add meaning for 'source' or 'companyId' beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('Append'), a specific resource ('one settleable CoS lesson'), and a clear scope ('for THIS operator only'). It also distinguishes itself from the sibling append_cos_preference by specifying the self-improve construction context and the 'settleable' qualifier. The purpose is 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 says when to use it ('Use after a clear win/miss on a call'), what content to include ('what worked, what failed, which principle'), and what not to include ('Short notes only — not transcripts'). It also provides explicit behavioral guidance about approvals and when to call it ('Call it on the first clear ask; the card is the yes — do not re-ask in chat'). This is exemplary 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?

The annotations already mark this as a non-read-only mutation, but the description adds meaningful context: persistence across sessions, re-injection on the next voice session mint, current-call application, and the write-tier approval workflow. It also clarifies the success signal ('the card is the yes'), which is not in the annotations.

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

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

The description is front-loaded with the core behavior and use cases, then delivers policy details in a compact second paragraph. The bracket section is dense but every clause adds operational guidance, so nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, it covers persistence, scope, approval requirements, timing, and expected response in enough detail to call it correctly. It doesn't explicitly address error/denied-approval behavior, but that is a minor gap given the schema and annotations.

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

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

With 100% schema description coverage, each parameter is already documented, including a concrete example for 'note'. The tool description contributes domain context but does not need to repeat parameter formats; it adds little 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 opening phrase 'Append one durable speech/taste preference for THIS operator only' names a concrete verb, resource, and scope. It also differentiates itself from the shared FreedomOS CoS template and from set_cos_preferences by emphasizing 'append' and 'this operator only.'

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

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

It spells out explicit triggers ('hard to follow', 'how cards should sound', 'remember I prefer…') and tells the agent to act on the first clear ask without re-asking. It establishes boundaries ('does not edit the shared FreedomOS CoS template') but does not name sibling alternatives such as set_cos_preferences or append_cos_lesson.

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

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

Annotations already mark readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds meaningful behavioral context about the write-tier approval flow (manager approval, recurring vs one-time approval) and the instruction not to re-ask, which is beyond the annotations.

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

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

The core description is one sentence, immediately stating the action. The additional approval block is somewhat long but provides essential usage context, so no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 append operation, the description covers the action, the spreadsheet target, and the approval side-effect. It doesn't need to explain return values since there is no output schema, and the parameters are fully documented in schema. It is complete enough for correct invocation.

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

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

The input schema already provides descriptions for all three parameters at 100% coverage. The description adds no further parameter meaning, so baseline 3 applies.

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

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

The description opens with a specific verb ('Append') and resource ('Google Spreadsheet'), clearly identifying the operation. It doesn't explicitly distinguish from siblings like batch_update_spreadsheet or update_sheet, but 'append' is a distinct operation; still, no sibling differentiation is provided.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the approval workflow: 'first use may require a manager's approval...' and instructs to call it on the first clear ask. However, it gives no guidance on when to prefer this tool over siblings like update_sheet or batch_update_spreadsheet, leaving tool selection ambiguous.

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

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

Goes well beyond annotations by explaining the sensitive-tier manager approval flow, the distinction between 'from-now-on' and 'just-once' approvals, and the instruction that the card itself is confirmation of success. It also clarifies that approved:false means rejection and never publishes, which is important given destructiveHint=true.

Agents need to know what a tool does to the 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 opening sentence is a crisp, front-loaded summary of the core action. The bracketed sensitivity note is dense but compact, covering manager approval, consent types, and call timing without 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 simple 3-parameter tool with full schema coverage and clear annotations, the description adds the only missing context: the sensitive-tier behavior and how to handle the confirmation. No output schema is needed here; the tool's effects and usage are fully covered.

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

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

Schema coverage is 100%, with each parameter already documented including the 'approved' default and the reject semantics. The description adds no new parameter information beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('Approve') and a resource ('a content item for publishing'), and immediately clarifies the dual action: 'or REJECT it with approved:false'. It gives concrete user phrases ('approve it', 'looks good', 'publish that') that distinguish this tool from siblings like publish_pipeline_item or get_pending_approvals.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Use when user says...' and lists triggers for both approval and rejection. It also gives behavioral guidance: 'Call it on the first clear ask; the card is the yes — do not re-ask in chat.' This tells the agent exactly when to invoke and how to handle the interaction.

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

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

The description goes well beyond annotations: it explains soft-delete semantics, confirms "No data is deleted or cascaded", and discloses the write-tier approval behavior including from-now-on vs just-once approvals and the instruction not to re-ask in chat. The destructiveHint=true annotation is not contradicted since flipping is_active still mutates state and can pause live automation.

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

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

The description is front-loaded with the core action, then gives trigger phrases and approval context in three compact, information-dense sentences. Every sentence earns its place and there is no filler or repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 mutating 4-parameter tool with no output schema, the description covers the action, reversible behavior, absence of cascade deletion, user-intent triggers, the restore flag, and the approval workflow. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds a useful natural-language mapping for restore:true, but it does not materially enrich parameter semantics beyond what the input schema already provides.

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

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

The description states a specific verb and resource: "Archive (or restore) a content pipeline" and clarifies it flips is_active off/on. It distinguishes itself from siblings like archive_playbook by making the resource explicit and by framing it as the UI's soft-delete/restore action.

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

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

It gives explicit trigger phrases: "archive this pipeline", "pause my newsletter automation", "turn off this pipeline", and "bring back my archived pipeline" with pass restore:true. It provides strong when-to-use guidance and approval-flow instructions, but it does not explicitly name an alternative tool or a when-not-to-use condition for hard deletion or pipeline edits.

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

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

Annotations already declare destructiveHint=true, so the description's job is to add nuance. It does so by clarifying that the delete is 'safe' and 'recoverable,' and it discloses approval requirements (write-tier, manager approval, 'card is the yes — do not re-ask in chat'). This goes beyond the annotations and improves agent behavior, though it does not mention any downstream effects on related 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?

The description is structured with a primary sentence, a routing line, and a bracketed approval note. It is front-loaded with the core purpose and the approval note is clearly separated. While the bracketed note is a bit long, it contains critical behavioral instructions and does not feel bloated. Overall efficient for the complexity involved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3-parameter tool with one required parameter and no output schema, the description covers the purpose, usage context, identifier options, and even the unusual approval workflow. It does not explain return values (not needed without an output schema) or what happens after archiving, but the essential information an agent needs to call this correctly is present.

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

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

The input schema has 100% description coverage, so all parameters are already documented. The description only adds a summary ('Identify by title or ID') that mirrors the schema's 'use this or playbook_title/id' notes. It adds no substantial new meaning beyond what the schema offers, matching the baseline of 3.

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

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

The description clearly states the action ('Archive a Playbook') and the resource, explicitly notes it is a 'safe delete — recoverable,' and defines the trigger use case: 'Use when the operator wants to retire a playbook.' This distinguishes it from other playbook tools (create, update, run, etc.) by focusing on retirement intent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 includes an explicit 'Use when' clause and a routing instruction ('Retire a Playbook → use this') that tells the agent exactly when to invoke it. However, it does not name alternative tools or state conditions when not to use it (e.g., if a permanent delete or edit is needed), leaving some ambiguity for edge cases.

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

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

Adds valuable behavioral context beyond annotations: the key is shown once, acts with the operator's authority, is scoped to the company, and the bot reads the role's brief every turn via get_my_role. It doesn't restate the destructiveHint, but the authority implications are disclosed.

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

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

The description is somewhat long and includes tangential detail (e.g., enumerating what get_my_role returns) that could be trimmed without losing essential guidance. It is still front-loaded with the core action and well-paragraphed, so it remains scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 4 params, no output schema, and mutation/destructive annotations, the description covers operation, outcome, parameter sourcing, approval workflow, and routing. Minor gaps like explicit replacement semantics are handled in the host parameter schema, so the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by instructing to resolve agent_id from get_team_roster and by giving host examples (Grok Bot, Claude, ChatGPT) that map directly to the host enum, helping the agent understand parameter provenance and values.

Input schemas describe structure but not intent. Descriptions should explain 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: attaching a bot to one role and retrieving a key. It distinguishes from sibling detach_agent_key by explicitly pointing to it as the stop action, and from other attach-like tools by specifying role attachment and the get_team_roster source for agent_id.

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

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

Provides explicit when-to-use conditions ('Use when the operator wants their own bot to wear a role instead of FreedomOS running it for them'), concrete user phrasing examples ('attach my bot / my Grok / Claude to <role>'), and names the alternative for stopping (detach_agent_key). Also covers approval nuance with 'call it on the first clear ask'.

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

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

Beyond the destructiveHint annotation, the description reveals crucial behavior: the PROGRESS vs. Fixed distinction based on file types, and the deployed-verified merge-close rail. It also discloses the write-tier approval process (manager approval, from-now-on vs. just-once) which the annotations do not cover. This is rich context that helps the agent anticipate 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 front-loaded with the core actionable verb and object, then flows into important conditional behaviors. The bracketed write-tier note is separated for emphasis. While slightly long, every sentence carries meaningful information and there is 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?

Given no output schema Equality, the description explains the key outcomes (PROGRESS vs. Fixed), error recovery (reopen_product_request), and permission requirements (write-tier approval). An agent has enough to decide when and how to invoke it 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 both `request_id` and `pr_url` are already well-documented. The description reinforces that the PR URL must already be a `freedom-ai` GitHub PR, but adds no new semantic details about parameter formats or constraints 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 opens with a specific verb and resource: 'Attach an existing freedom-ai GitHub PR URL to a product request.' It clearly differentiates from `open_product_request_draft_pr` by focusing on attaching an existing PR rather than opening a new one, and it references `reopen_product_request` for reversal, establishing its distinct role in the workflow.

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

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

Explicitly states when to use: 'Use when you (or a coding agent) opened a real PR for the filed fix.' It also specifies what happens in different cases (draft PRs attach as PROGRESS, not Fixed) and directs to the alternative `reopen_product_request` for false Fixed. The write-tier approval note gives additional operational context without 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?

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds valuable context beyond them: the tool makes external calls to third-party LLMs (an important side-effect/cost signal) and explicitly disclaims answering questions or delegating work. It falls short of 5 only because it doesn't disclose rate-limit or cost implications of firing queries at four external providers.

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

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

The description is front-loaded with the core purpose in the first sentence, then the competitive-audit framing, then a tightly organized routing block. Every sentence earns its place — there is no filler, and the negative routing content is high-value despite its length.

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

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

For a 5-parameter tool with external side effects and no output schema, the description covers purpose, scope, routing exclusions, and alternatives thoroughly. It is missing only a note on what the result looks like (e.g., per-provider mention report) and cost/rate-limit transparency, which would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline of 3 applies; the schema already richly documents providers (mapping enum values to brand names and noting Perplexity's Sonar Pro live-search advantage) and prompt semantics. The tool description adds no additional parameter-level meaning beyond what the schema provides, but no compensation is needed given full coverage.

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

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

The description names a specific verb and resource ('Audit whether FreedomOS appears in AI-generated search results') and explains the concrete mechanism (sending queries to Claude, Grok, Gemini, Perplexity and checking for brand mentions). It also distinguishes itself from siblings by explicitly stating it is not a general research or Q&A tool, which separates it from browse_url, read_web_page, and query_sme 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 Routing paragraph is exemplary: it gives positive routing (SEO/GEO visibility, competitor, and content-strategy research with concrete example queries) and explicit negative routing (NOT for a second opinion, NOT to answer user questions, NOT general research) while naming the exact alternatives (browse_url/read_web_page). An agent can route this tool correctly without any inference.

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

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

Annotations already mark it as destructive and non-idempotent)Skip the safety profile. The description adds valuable context about the approval workflow: first-use may require manager approval, approval granularity (from-now-on vs just-once), and the instruction to regard the card as consent and not re-ask. This goes beyond the annotations without contradicting them.

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

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

The first sentence is a crisp purpose statement. The longer bracket note is relevant and actionable, though slightly verbose with phrases like 'the card is the yes — do not re-ask in chat.' Overall it's compact and stays on-topic.

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

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

The tool has three fully documented parameters and annotations covering destructiveness. The description adds the approval context and write-tier note, which are important for an agent to invoke it appropriately. It doesn't explain error handling or partial failures, but that is not required given the schema and annotations.

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

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

Schema description coverage is 100%, so all three parameters (spreadsheet_id, requests_json, companyId) are already documented. The description's mention of 'formatting, merging' loosely maps to requests_json but adds no specific semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (Perform batch operations), a resource (Google Spreadsheet), and examples (formatting, merging). The word 'batch' distinguishes it from siblings like append_to_sheet and update_sheet. The purpose is immediately 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 implies usage for multi-change spreadsheet operations via the term 'batch' and mentions 'formatting, merging' as typical cases. The approval note gives guidance on when to call (first clear ask) but does not explicitly contrast with alternative tools or specify when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond those: it clarifies this is a catalog lookup against the 'LIVE MCP catalog' and explicitly says 'this tool does not write files,' reinforcing the non-mutating behavior in a way that is directly relevant to the invention-use case.

Agents need to know what a tool does to the 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 reasonably scannable and front-loaded, but it repeats the same example list ('glossary, wiki, memory store, voice pack, task list') in both the opening paragraph and the Routing section. The core guidance is clear, but the redundancy makes it less tight than it could be.

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

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

For a simple optional-parameter read-only tool with strong annotations and full schema coverage, the description covers when to call it, what it returns ('what FreedomOS already offers... from the LIVE MCP catalog'), and the key behavioral caveat that it does not write files. No output schema exists, but the return purpose is sufficiently explained for an agent deciding to invoke this 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%, and the schema already explains both optional parameters, including the 'job' field and companyId requirement. The description mainly restates the job concept but adds no new parameter-level semantics beyond what the input schema already documents, so the baseline of 3 is appropriate.

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

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

The description states a specific action with concrete examples: 'Before inventing a parallel glossary, wiki, memory store, voice pack, task list... call this. Returns what FreedomOS already offers for that job from the LIVE MCP catalog.' It clearly identifies the resource being checked and explains the unique pre-inventing role, distinguishing it from the many 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?

The description gives an explicit trigger condition ('before inventing... call before_inventing_check_fo FIRST') and adds a strong exclusionary rule ('Do not invent a second knowledge system'). It references FreedomOS's existing Knowledge/canon, voice, and work tools as alternatives, though it does not name specific sibling tool names explicitly.

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

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

Annotations already mark this as non-read-only and destructive, and the description adds meaningful behavioral context: it names an existing publication rather than creating one, requires the operator/authorized host context, and explains approval behavior ('a just-once approval re-asks next time'). This goes well beyond what annotations provide.

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

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

The description is well-organized with a clear lead sentence, routing guidance, and approval notes. There is some redundancy between the first paragraph and the Routing section, but overall it remains focused 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?

For a two-parameter tool with no output schema, the description covers the trigger conditions, prerequisites, non-actions, routing rules, and approval/confirmation behavior. Nothing essential is missing for an agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters. The description reinforces that publication_id must come from the existing Beehiiv connection, but adds little semantic value beyond the schema's own parameter descriptions.

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

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

The description states a specific verb (bind), resource (Beehiiv newsletter), and outcome (destination for website articles). It also explicitly distinguishes itself by saying it does not send, bless, or publish, which differentiates it from nearby siblings like publish_hub.

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

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

The description explicitly says when to use the tool: when an article or pending words card has no newsletter destination and Beehiiv is already connected. It also gives clear when-not guidance ('does not send, bless, or publish'), warns against typing hub config by hand, and explains the approval flow for first use.

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

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

Beyond the annotations, the description discloses the browser-credit cost, the sensitive-tier approval behavior, and that a screenshot image is returned for vision analysis. It does not elaborate on the destructiveHint annotation (e.g., click/fill actions could cause page side effects), but the optional actions and JS-interaction framing provide partial context; there is no contradiction.

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

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

The main purpose is front-loaded in the first sentence, followed by use cases in the second. The routing and approval paragraphs are somewhat long but all earn their place by giving operationally important constraints (cost, alternative tool, approval semantics).

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 still tells the agent what comes back (page content and a vision-analyzable screenshot). Combined with cost, routing, and approval guidance, an agent has enough context to invoke it correctly; a little more detail on return format would be the only 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 coverage is 100%, so the schema already documents url, actions, and companyId. The description mainly reinforces the screenshot behavior and cost rather than explaining individual parameters, which is acceptable at the baseline for complete 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 names a specific verb and resource ('browse a web page in a real browser and take a screenshot') and states what it returns: page content and a screenshot image. It also delineates the tool from read_web_page by emphasizing visual inspection and JS interaction, so the purpose is unmistakable.

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

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

It gives explicit when-to-use conditions (need to SEE the page, interact with JS, capture visual evidence) and an explicit when-not-to-use alternative (read_web_page for simple text extraction). It even adds a cost/credit comparison, so the agent can route correctly.

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

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

Annotations already indicate destructive and non-idempotent behavior, but the description adds crucial caveats: 'Does not reverse work the host already did,' scope restriction, and the approval workflow. This meaningfully extends what structured annotations convey, even though it doesn't detail all possible 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 core sentence is concise and front-loaded with purpose and usage. The bracketed approval guidance is additional but relevant; the description is efficient without being bloated.

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

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

For a single-required-parameter cancel tool, it explains the object, side effects, scope, and approval flow. It lacks return/error handling details, but no output schema exists and those are not essential for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds little beyond 'pending' and scope; the mention of 'target_session_id' could be slightly confusing since the parameter is named 'id'. 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 a specific verb and resource: cancel a pending attention directive, with explicit reasons (operator changed mind / wrong target). It distinguishes from siblings like create_attention_directive and ack_attention_directive by emphasizing cancellation of pending directives and scoping to 'THIS operator only.'

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

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

Provides explicit trigger scenarios: operator says drop/cancel that instruction to Grok or Claude, or CoS realizes the target_session_id was wrong. It also includes operational guidance about write-tier approval and not re-asking in chat. However, it doesn't name sibling alternatives directly, so it's not a perfect 5.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds valuable context: it marks the commitment as cancelled, distinguishes cancellation from completion, and explains the write-tier approval behavior ('first use may require a manager's approval', 'just-once approval re-asks next time'). This goes beyond the structured annotations without contradicting them.

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

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

The first sentence immediately states the core action, and the second provides usage triggers and the sibling alternative. The approval paragraph is somewhat dense but each clause carries operational value, so it earns its place without being bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 destructive action with no output schema, the description covers the core semantics, when to use it, the key alternative, and the approval interaction. The schema covers parameter identification. A brief note on irreversibility or side effects would make it fully complete, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the optional reason, companyId, title_search, and commitment_id. The description adds no extra parameter-level meaning, which is acceptable given the high schema coverage.

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

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

States a specific verb and resource ('Cancel a commitment') and clarifies the semantic distinction from completion ('without completing it — marks it cancelled'). It explicitly names the sibling alternative complete_commitment, so an agent can disambiguate without opening other definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 concrete trigger phrases ('cancel that', 'never mind, drop it', 'that's not happening anymore') and an explicit exclusion ('For finished work, use complete_commitment instead'). The approval-flow guidance also tells the agent exactly when to invoke the tool and not to re-ask after the user approves.

Agents often have multiple tools that could apply. Explicit usage 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 describes a non-destructive save operation ('save for later') while the annotations declare destructiveHint=true, which is a direct contradiction; the write-tier approval detail is useful but does not resolve or disclose the destructive behavior. Per the contradiction rule, this dimension is scored 1.

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

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

The purpose is front-loaded, and each part adds distinct value: trigger, exclusion, and approval behavior. The bracketed write-tier block is dense but necessary; slight redundancy between 'Capture an idea' and 'Use when user shares an idea' keeps it from a 5.

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

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

For a simple 3-parameter create tool, the description covers why and when to use it and the approval flow, which is most of what an agent needs. It is incomplete because it contradicts destructiveHint, and the companyId parameter's relevance to 'user's Ideas' is unexplained.

Complex tools with many parameters or behaviors need more documentation. 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 explains content, companyId, and source_url. The description adds no new parameter-level meaning beyond calling content an 'idea' and does not clarify whether/why companyId is needed for this personal Ideas tool; 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?

Opens with a specific verb and resource: 'Capture an idea into the user's Ideas.' It then gives the trigger condition ('user shares an idea they want to save for later') and explicitly contrasts with save_knowledge, so an agent can tell it apart from its nearest sibling without inspecting schemas.

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

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

Explicitly states when to use ('use when user shares an idea...') and when not to ('Sitting debriefs and company notes are save_knowledge, not Ideas'). It also adds operational guidance on approval: when to call, what counts as approval, and not to re-ask in chat.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: it uses REAL Customer Evidence first when available, then falls back to a labeled simulated ICP, and it returns honest engagement-oriented feedback.

Agents need to know what a tool does to the 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 focused sentences cover what the tool does, what it returns, and when to use it. The phrasing is slightly metaphorical ('customer truth'), but the added explanation keeps it efficient and readable.

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

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

For a read-only evaluation tool with complete parameter schema and clear annotations, the description is largely sufficient. It explains the process, output, and usage context; only a more concrete output format would make it fully complete, and there is no output schema to supply that.

Complex tools with many parameters or behaviors need more documentation. 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 does not add further meaning about parameters like target_icp or deliverable_type, so it neither helps nor hurts beyond the baseline.

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

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

The description clearly states what the tool does: it evaluates a deliverable against customer evidence and simulated ICPs, then returns feedback. It is distinct in substance from generic review tools, but it does not explicitly name or contrast any sibling tool.

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

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

The description gives explicit guidance: 'Use on customer-impact deliverables before sending.' It establishes a clear context and timing for use, though it does not provide when-not-to-use guidance or name 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?

The description says 'Idempotent: existing projects are left in place (Workers scripts are never overwritten),' but the annotations set idempotentHint=false. This is a direct contradiction. It also promises non-overwrite behavior while annotations mark destructiveHint=true, making the behavioral claims unreliable.

Agents need to know what a tool does to the 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 minimal but front-loaded with purpose and use, followed by routing and approval behavior. Every section carries operational value, and the structure supports quick scanning, though the bracket approval note adds a slightly informal tail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-tier tool with 7 parameters, it covers prerequisites, routing, idempotency (though contradicted), approval flow, and alternatives. It does not describe the output or success/failure payload, which is a gap given the absence of an output schema, but overall it is quite 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 baseline is 3. The description adds meaning by clarifying that GitHub source params apply only to Pages ('Optional GitHub source (Pages)') and that hostname is a CNAME binding. This goes beyond the schema without restating every field.

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

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

The description opens with a specific verb and resource: 'Claim or create a Cloudflare Pages or Workers project on this company's standing deploy token.' It also disambiguates from related tools in the Routing section by naming this tool, request_connector, and get_cloudflare_hosting_status as distinct destinations.

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

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

It explicitly states when to use the tool: 'Use when an operator-agent needs a Cloudflare preview or hosting bind.' It also provides alternative routing: connect token → request_connector Cloudflare, status → get_cloudflare_hosting_status, and explicitly says 'Not invoke_integration.' This is clear when/when-not guidance.

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

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

The description adds meaningful behavioral context beyond the annotations: it is a write-tier action, first use may require manager approval, approval can persist or be one-time, and the card itself is the confirmation. This is valuable since annotations only mark destructiveHint=true. It does not detail what exactly is mutated or destroyed, but the approval and workflow context is strong.

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

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

The main description is front-loaded with the core action and use case, followed by a compact operational note. The approval-mode text is slightly dense but earns its place because it affects how the agent should call the tool. No filler is present.

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

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

For a write tool with no output schema, the description conveys purpose, trigger condition, output concept (paste-ready claim), and approval behavior. It is complete enough for an agent to decide and invoke correctly. It could be more explicit about side effects and return value, but those are partially covered by the schema and the phrase 'paste-ready claim recipe.'

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

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

The input schema already has 100% coverage with clear descriptions for all three parameters, so the baseline is 3. The description reinforces the meaning of request_id as a 'filed request' and the claim-paste workflow, but it does not add meaning beyond what the schema already provides.

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

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

The description states a specific action—mint a paste-ready Builder claim recipe—and names the target audience and resource (product-inbox members, filed request). The clarification that it does not run the coding agent helps define scope. It does not explicitly differentiate from closely related sibling tools like attach_product_request_pr or submit_product_request, so it falls short of a 5.

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

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

The description explicitly says when to use it: when a product-inbox member needs the claim paste for a filed request. It also provides operational guidance about approval types and instructs calling on the first clear ask without re-asking. It does not mention when not to use it or name alternative tools for similar cases.

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

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

Annotations mark destructiveHint=true, and the description aligns while adding meaningful behavioral context: write-tier approval requirements, approval types (from-now-on vs just-once), and the instruction not to re-ask in chat after the card approves. This goes beyond what annotations alone provide.

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

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

The description is compact and front-loaded: it states the core action first, then trigger examples, then approval guidance. Every sentence earns its place and avoids 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 destructive tool with three fully documented parameters and no output schema, the description provides everything needed to invoke it correctly: trigger phrases, scope of effect, and approval workflow. Even without an output schema, no critical calling information is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no new parameter-level detail beyond what the input schema states, such as the effect of output_format or the source of pipeline_id.

Input schemas describe structure but not intent. Descriptions should explain 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 begins with a specific verb and resource: 'Reset all learnings for a pipeline and start fresh.' It is clearly distinct from sibling tools like list_pipeline_learnings (read-only counterpart) and update_pipeline_style_guide (targeted update), even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 trigger phrases ('forget what you learned', 'start fresh with the style') and instructs to call it on the first clear ask. It provides clear context for when to invoke the tool, though it does not explicitly state when not to use it or name an alternative tool.

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

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

Annotations already flag this as destructive and non-read-only. The description adds useful operational context beyond the annotations by explaining the write-tier approval behavior: first use may require manager approval, approval can be scoped as from-now-on or just-once, and the agent should act on the first clear ask rather than re-asking in chat. This is valuable behavioral guidance.

Agents need to know what a tool does to the 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 core purpose and usage guidance are front-loaded in one crisp sentence. The bracketed approval note is somewhat dense but contains important operational instructions. It is efficient overall, though the approval explanation could be tightened without losing meaning.

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

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

For a simple completion action with fully documented parameters and destructive annotations, the description covers the key operational concerns: when to invoke it, what approval flow to expect, and how to handle the response ('the card is the yes'). It does not discuss reversibility, but the destructiveHint annotation already communicates that risk.

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

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

The input schema already describes all parameters (companyId, title_search, commitment_id) with 100% coverage, so the baseline applies. The description does not add parameter-level guidance, such as preferring commitment_id over title_search or clarifying which identifier to use first, but it does not need to because the schema is self-explanatory.

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

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

The description opens with a specific verb and resource: 'Mark a commitment as completed.' It also gives clear trigger conditions ('user says they finished something or a deadline has passed'), which makes its purpose distinct from sibling tools like cancel_commitment, update_commitment, or complete_my_activity.

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

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

The description explicitly states when to use the tool: when the user reports finishing something or when a deadline has passed. It does not name alternatives or state when not to use it, but the usage context is clear enough for a simple state-transition 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?

The description explains the validation behavior in detail: the deposit must exist in the company, must have been made since the job last ran, and must not have already stamped another job. It also discloses the not-done outcome, the Preflight exception, and the write-tier approval behavior beyond what annotations convey.

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

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

The description is long but each sentence carries operational value. It is organized with clear routing and approval guidance, though it could be tightened; the write-tier approval paragraph is dense and mixes multiple instructions together.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 nested deposit object, no output schema, and complex validation semantics, the description covers everything an agent needs: when to call, what to pass, how the stamp is verified, the exception for Preflight, key behavior, and routing to an alternative. Nothing critical is missing.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it maps each deposit kind to the tool that produces it, clarifies that the activity_name must match the brief exactly, explains when agent_id is omitted, and defines the purpose of note. This goes well beyond the schema field descriptions.

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

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

The description opens with a specific verb and resource: 'Stamp one due job as done AFTER you deposit the work, and prove it.' It clearly identifies this as the completion action for due activities from get_my_role, and the Routing note differentiates it from remove_agent_activity.

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

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

It states exactly when to use the tool: when get_my_role listed the activity in due_now and the deliverable has already been deposited. It also provides an explicit routing rule, 'After depositing a due job → complete_my_activity (not remove_agent_activity)', and specifies when agent_id is required.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds useful approval behavior details ('first use may require manager approval', 'just-once approval re-asks next time') and instructs the agent to call the tool on the first clear ask and not re-ask in chat. 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 front-loaded with the core purpose and cardinality, followed by a clearly bracketed approval note. Every sentence earns its place; the approval note is dense but directly relevant to agent behavior. 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 complex tool with 8 parameters and nested config objects, the description plus schema is largely complete: purpose, widget scope, approval flow, and input semantics are covered. The only notable gap is that it does not mention how to discover existing widget IDs for updates, though the sibling list_dashboard_widgets makes that inferable.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter. The description adds only high-level context about widget types (metrics, charts, tables, timelines) but no parameter-specific meaning beyond what the input schema provides. This is the appropriate 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 states a specific verb and resource: 'Create or update a widget on your agent dashboard.' It also clarifies cardinality ('Each call creates or updates one widget'), which distinguishes it from sibling tools like list_dashboard_widgets and remove_dashboard_widget. This is far more specific than the tool's name/title.

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

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

The description gives clear context for when to use the tool: to display key metrics, charts, tables, or timelines that help the user understand work at a glance. It also provides operational guidance about write-tier approvals and not re-asking after the approval card is shown. However, it does not explicitly name alternatives or exclusion cases, such as using list_dashboard_widgets to find widget IDs before updating.

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

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

Annotations mark destructiveHint=true and readOnlyHint=false, and the description aligns by framing this as a write-tier action that runs the same pipeline as tapping Approve and may require manager approval. It adds behavioral nuance beyond annotations: integrity rails, grant_mode standing vs once, and not inventing IDs. There is no contradiction.

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

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

The description is organized into three logical chunks: overview, routing, and write-tier grant note, with the core instruction front-loaded. It is longer than minimal but each section earns its place, though the bracket note is dense and could be tightened. No filler or repetition that hurts usability.

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

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

For a 6-param mutation tool with no output schema, it covers required inputs, approval_id provenance, decision values, grant modes, and preconditions. It could say what happens after reject/later or what the return indicates, but calling the tool correctly does not require that. Completeness is strong for the task at hand.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by sourcing approval_id from approval_required and explaining the standing/once grant modes in prose. It does not mention every parameter, but the schema already documents companyId and the optional audit fields. Decision semantics are expanded slightly via 'yes/no/go also accepted'.

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

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

States a specific action ('Confirm'), a specific resource ('pending MCP capability approval'), and the input pathway ('approval_id from the approval_required tool result'). It is clearly distinct from siblings like get_pending_approvals or approve_pipeline_item because it targets the MCP approval card flow. The title is generic, but the body fully carries the meaning.

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

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

Explicitly instructs when to call: 'After a tool returns approval_required', and on voice when the operator says approve/yes or reject/no. It also gives exclusions: 'Do NOT invent an approval_id' and 'do not re-ask in chat'; the card is the yes. No alternative tool is named, but the routing is specific enough to drive 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?

Annotations mark this as non-read-only and destructive, and the description adds substantial context: company-manager-only permission, sensitive-tier approval behavior, key storage in Vault, the 'request≠grant' nuance, and the Is Agentic 404-until-scan caveat. This goes well beyond the annotations without contradicting them.

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

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

The description is long but well-structured with line breaks and distinct sections (purpose, routing, sensitive-tier). Every sentence adds meaningful operational detail, though a few policy notes (e.g., 'do not re-ask in chat') could be trimmed for tighter focus.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no output schema, the description is remarkably complete: it covers prerequisites, permission tiers, routing, post-connect behavior, and a known edge case (404 before scan). An agent has everything needed to decide when to call it and what to expect after the call.

Complex tools with many parameters or behaviors need more documentation. 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 parameters. The description adds value with extra constraints: 'Never a private/loopback host' for server_url, 'At most 8' headers, and the default host behavior for name; it also clarifies that Authorization/API-key headers are refused and keys stay in Vault.

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

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

The description opens with a specific verb and resource: 'Bind a remote Streamable HTTP MCP onto this company from an https URL.' It also states the post-conditions (tools appear on list_integrations and run through invoke_integration), which distinguishes it from siblings like request_connector and start_oauth.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: 'Use when an operator or GM wants this company to call a public Streamable HTTP MCP... without Composio or a host-seat paste' and 'Autonomous agents must call request_connector with a vetted name instead — they never supply a URL.' The routing section further clarifies Operator/GM vs. agent flow.

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

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

Beyond the destructiveHint annotation, the description discloses important async behavior: the tool only queues a sticky note, does not wake the host, does not type into their UI, and requires the session to poll. It also adds write-tier approval context ('first use may require a manager's approval', 'the card is the yes — do not re-ask in chat'), which is meaningful operational context not available from 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 dense but well-organized: the core queueing semantics and usage triggers are front-loaded, and the approval caveat is isolated in a separate bracketed block. Every clause adds useful context, though the write-tier block is slightly elaborate for a tool description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 what the tool does, when to invoke it, how the polling model works, how to choose target_session_id, and what approval behavior to expect. For a side-effectful queueing tool with no output schema, the agent has enough to select and invoke it 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 the baseline is 3. The description adds value by explaining that target_session_id must match what the host polls and gives concrete examples (grok-<id>, claude-<id>, grok-bot-<agent-slug>). It also clarifies that instruction should be an imperative, not a transcript dump, which supplements the schema's 'one clear instruction' phrasing.

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

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

The description opens with a specific verb and resource: 'Queue a short instruction for an external agent session' and then names concrete host types (Grok terminal, Claude Code, Grok Bot). It clearly differentiates itself from polling/list tools by stating 'Pull sticky only' and adding that FreedomOS does not wake or type into the host UI.

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

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

The description gives explicit trigger phrases ('tell Grok…', 'have Claude…', 'send this to my Grok Bot…') and explains routing intent for CoS. It provides the complementary complementary polling path via 'poll-fo-directives.sh or list_attention_directives' and instructs the agent to 'Pass the same target_session_id the host polls,' making both when-to-use and how-to-use explicit.

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

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

The description discloses significant behavioral traits beyond annotations: pricing ($47/mo), fail-closed behavior, approval requirement, the purpose of the companyId parameter, and explicit note that it does not hire. These are not present in annotations, adding rich context for agent decision-making.

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

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

The description is long but well-structured with a clear purpose statement, side-effect details, routing, and a bracketed approval note. Each sentence carries information; redundancy is minimal. It could be tightened, but the structure aids comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 billing side effects, approval flows, and follow-up actions, the description covers all necessary context: pricing, payment failure handling, approval mechanics, and post-create next steps. It even explains the companyId usage. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, but the description adds crucial meaning, especially for companyId: 'Pass companyId of a company you already manage so that yes-card can land — it is not the company being created.' This goes beyond the schema's generic description and clarifies a non-obvious parameter purpose.

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

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

The description clearly states 'Create a new company in this operator's portfolio' with a specific verb and resource. It distinguishes itself from update_company by explicitly noting 'Not update_company (that's an existing company)' and clarifies it does not hire, eliminating ambiguity among siblings.

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

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

Provides explicit routing: 'new company / add a business / another venture → create_company' and states 'Not update_company'. It also instructs when to use ('Use when the operator wants another business in FreedomOS from chat or MCP') and includes follow-up tool suggestions, leaving no inference 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write-tier approval note adds context beyond the schema. The description discloses that title/description flow verbatim into marketing and that first use may require manager approval. It doesn't fully explain what 'destructive' means here, but the approval and verbatim-flow details are valuable.

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

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

The description is compact and front-loaded with the core action and trigger phrases. The routing and approval notes are dense but relevant. Slight redundancy in the approval section ('a from-now-on approval makes future calls seamless, a just-once approval re-asks next time') could be trimmed, but it earns its place.

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

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

For a write-tier tool with 8 params and no output schema, the description covers the key context: when to call, what to call first, and approval behavior. It doesn't describe the return value or what happens after creation, but the routing note and trigger phrases make it sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters. The description adds context for title/description (verbatim flow into marketing) but doesn't add meaning for the other parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Add a new feature to the Feature Index') and gives concrete trigger phrases ('I built X', 'add feature Y'). It also distinguishes the tool from siblings like update_feature, retire_feature, and list_features by framing it as the creation entry point.

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

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

The description explicitly says when to use it ('Use when user says...') and provides routing guidance ('call get_product_context first'). It also includes approval-tier guidance ('Call it on the first clear ask; the card is the yes — do not re-ask in chat'), which is unusually actionable for an agent.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write nature is known. The description adds valuable behavioral context: an approval workflow, approval-mode semantics, auto-creation routing via a sibling, and explicit instruction not to re-ask after the first clear request. It does not explain the destructiveHint implication, but the annotation covers that flag.

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

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

The description is front-loaded with the core purpose, followed by use cases, routing, and approval behavior. It is slightly longer than necessary, especially the approval bracket, but every sentence conveys operationally relevant guidance and no content is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 two fully documented parameters, a clear routing rule, approval guidance, and examples, the description is complete for an agent to call this tool correctly. No output schema exists, but the return value is not essential for deciding when or how to invoke the tool.

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

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

Schema description coverage is 100%, and both 'name' and 'companyId' are already well described in the input schema. The description reinforces nesting via 'partners/acme' but adds no meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource ('Create a folder in the knowledge base for organizing files') and gives concrete use cases and nesting examples. It also names the sibling alternative, save_knowledge, that can auto-create folders, so an agent can distinguish this tool's role without ambiguity.

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

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

The Routing section explicitly says folders auto-create via save_knowledge(folder: ...) and that this tool should only be called to pre-create an empty folder. It also provides operational guidance about approval tiers, when to call, and not to re-ask, making when-to-use and when-not-to-use clear.

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

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

Annotations already signal readOnly=false, destructiveHint=true, and openWorldHint=true, so the description doesn't need to repeat those. It adds valuable behavioral context about default formatting ('beautifully formatted docs') and the write-tier approval flow, which annotations cannot convey.

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

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

The description is front-loaded with the core purpose and stays relevant throughout. The write-tier approval paragraph is slightly verbose, but it carries essential operational information that would otherwise be missing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five parameters, no output schema, and annotations covering the safety profile, the description covers purpose, use cases, formatting behavior, and approval semantics. A minor gap is that it doesn't explain what kind of result the caller should expect, but that's not critical for invoking 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 the baseline is 3. The description adds meaning beyond the schema by mapping use cases ('JDs, deliverables') to the folder enum and explaining the default behavior of format_for_humans. It doesn't add detail for title or companyId, but those are self-explanatory.

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

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

The description opens with a specific verb and resource: 'Create a new Google Doc in the user's FreedomOS Drive folder.' It also enumerates concrete use cases ('JDs, deliverables, and shared documents'), which clearly separates it from sibling tools like read_google_doc and update_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?

It explicitly states when to use the tool ('Use for JDs, deliverables, and shared documents') and even gives workflow-level guidance about acting on the first clear ask. It does not name an alternative tool to use instead, so it falls short of the full when-not guidance.

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

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

Annotations indicate destructiveHint=true, which aligns with the creation action. The description goes beyond annotations by disclosing the write-tier approval requirement, which is a critical behavioral trait not covered by annotations. It also clarifies that the approval card is the yes and not to re-ask, adding useful interaction guidance.

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

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

The description is moderately long but front-loaded with the primary purpose and usage conditions. The routing guidance and approval note are relevant but add length. Slightly overwritten yet 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?

For a complex tool with 13 parameters and nested objects, the description covers the creation context, routing, failure mode, and approval flow. The schema covers parameters, and no output schema is present, so the description's focus on inputs and process is appropriate. It is complete for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds value by explaining the 'name' parameter is an internal targeting label and that publicName should be used for published copy, reinforcing the distinction. It also clarifies the 'class' parameter effectively.

Input schemas describe structure but not intent. Descriptions should explain 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 (Create a NEW Ideal Customer Profile), the resource (ICP), and the condition for use (when get_icps returns hasICPs:false or to add another). It also differentiates from update_icp explicitly, providing strong sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides when to use (create when none exist or add another), when not to use (to change existing use update_icp), and prerequisites (consult get_product_context + get_setup_state before authoring). It also warns about duplicate names and to use update_icp 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?

Annotations already communicate readOnlyHint=false, idempotentHint=false, and destructiveHint=true. The description adds valuable behavioral context beyond those annotations by explaining the write-tier approval flow, including first-use approval, from-now-on vs just-once approvals, and the instruction not to re-ask in chat. No contradiction with annotations was found.

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

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

The description is compact and front-loaded: two sentences state the purpose and objective-identification mechanism, and a bracketed approval note carries the operational guidance. There is no filler, and every sentence adds necessary 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 has 13 parameters, all fully described by the input schema, and annotations already cover safety properties, the description provides the missing approval-flow context and the core purpose. It lacks an explicit description of the return value, and there is no output schema, but the schema and annotations make the tool callable with sufficient confidence.

Complex tools with many parameters or behaviors need more documentation. 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 and the schema already documents all 13 parameters in detail. The description adds one useful semantic note about identifying the parent objective 'by title or ID,' which maps to objective_id and objective_title, but it does not significantly extend parameter understanding beyond the schema.

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

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

The description clearly states a specific action and resource: 'Add a key result to an objective (the KR in OKR).' It also clarifies that key results are measurable outcomes and that the parent objective can be identified by title or ID. However, it does not explicitly differentiate from related siblings like generate_key_results or update_key_result, so it falls just short of full sibling-level distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 actionable invocation guidance in the approval note: 'Call it on the first clear ask; the card is the yes — do not re-ask in chat.' It also implies the tool is used for adding a measurable outcome to an objective. But it does not compare against alternatives or state when not to use this tool, leaving some tool-selection inference to the agent.

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

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

Beyond the annotations, the description discloses that everything is created in a paused state spending nothing, that primary_text must come from draft_ad_variants or operator-supplied copy, and that activation is a separate human-approved step. It also encodes the sensitive-tier approval behavior, which is valuable context the structured fields don't carry.

Agents need to know what a tool does to the 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 core behavior is front-loaded in the first sentence, and the routing and approval sections are compact and non-redundant. Every paragraph provides decision-relevant information: what is created, what to run first, and when approval is 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?

For a complex 11-parameter tool with nested objects and no output schema, the description covers when to call, what gets created, prerequisite copy generation, activation separation, and approval handling. Very little is left for an agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning for primary_text, cta, and campaign_name by explaining that copy should be picked from draft_ad_variants and that the hook tag belongs in campaign_name. It doesn't add per-parameter detail for all 11 fields, but the schema already covers those well.

Input schemas describe structure but not intent. Descriptions should explain 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 opening sentence states a specific verb and resource: 'Create a complete Meta ad draft — campaign + ad set + creative + ad — ALL in PAUSED state.' It clearly distinguishes itself from draft_ad_variants and set_meta_ad_status, so an agent can tell what this tool does and does not do.

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

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

The description explicitly says 'Use when the user wants to set up or draft an ad' and gives an explicit routing rule: run draft_ad_variants first if copy isn't already picked, then create here. It also names set_meta_ad_status as the separate activation step and calls out the operator-copy exception, giving clear when-to-use vs. alternative guidance.

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

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

Beyond the annotations, it discloses the write-tier approval behavior, the difference between from-now-on and just-once approvals, and the 'card is the yes; do not re-ask' interaction rule. This is exactly the kind of non-obvious behavioral context annotations alone don't carry.

Agents need to know what a tool does to the 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 purpose is front-loaded and the workflow context is useful, but the approval bracket is fairly long and the 'no way to measure progress' sentence is explanatory rather than strictly necessary. Still, nothing is redundant enough to feel padded.

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

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

The combination of schema, annotations, and description covers what the tool does, the approval flow, and the follow-on tools. The main gap is that it doesn't mention what the call returns (e.g., an objective ID to feed into create_key_result) and there is no output schema to fill that in.

Complex tools with many parameters or behaviors need more documentation. 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%, with each parameter already documented, so the baseline applies. The description adds no additional parameter-level detail beyond reinforcing that title should be aspirational, which the schema already states.

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

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

States 'Create a new objective (the O in OKR)' with a clear verb and resource, and further defines objectives as 'aspirational goals.' It differentiates from sibling tools by explicitly placing this before generate_key_results and create_key_result in the OKR workflow.

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

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

Gives a clear when-to-use signal ('Call it on the first clear ask') and a direct post-create workflow: use generate_key_results, then create_key_result. It doesn't explicitly contrast with update_objective or delete_objective, but the workflow guidance is concrete enough for routing.

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

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

Beyond annotations, the description clarifies important side effects: 'Does not charge FreedomOS. Does not move money until the payer pays.' It also explains the approval behavior in detail: first use may require approval, from-now-on vs just-once, and when to call without re-asking. This is valuable behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with purpose, then usage conditions, then approval behavior. Each section earns its place, and the approval paragraph is dense but directly actionable for an agent. 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?

For a tool with 5 parameters and no output schema, the description covers the key operational facts: what it returns ('checkout URL'), when it is valid (charges_enabled), side effects (no money movement until payer pays), and approval nuances. An agent has enough 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 the schema already documents all parameters thoroughly. The description adds no significant parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the description does not need to compensate.

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

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

The description clearly states the verb and resource: 'Create a Stripe Payment Link so this company can collect a real payment.' It enumerates use cases (sponsor, invoice, one-off) and provides routing context. However, it does not explicitly distinguish itself from the sibling get_checkout_link, though the overall intent is 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 explicitly says when to use the tool: 'Use when get_receive_status says charges_enabled (or start_company_receive already finished).' It also gives router-style direction: 'Payment link / sponsor checkout / collect money after Stripe KYC → this tool.' It does not state when-not-to-use or name alternative tools explicitly, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, indicating a write operation with possible side effects. The description adds the write-tier approval note ('first use may require a manager's approval...'), which is valuable operational context not present in annotations. It doesn't detail exact side effects or what gets destroyed, but the approval disclosure covers a key behavioral aspect.

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

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

The description is moderately long but well-structured: core purpose, usage triggers, output types, and an approval note. It is front-loaded with the main action and trigger examples. Each sentence contributes useful information, though the output-type enumeration adds some length. It remains clear and scannable.

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

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

For a 5-parameter tool with a nested object and no output schema, the description covers usage triggers, output types, and the approval workflow. The schema documents companyId membership requirements, and the description explains the output semantics. It doesn't describe the return value or post-creation steps, but those are not critical for invoking the tool. It is sufficiently complete for an agent to call it 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 every parameter is documented. The description adds extra semantics for the output parameter by elaborating on each output type (e.g., team_update is internal email via FreedomOS, customer_newsletter requires Email MCP), which goes beyond the schema enum text. It doesn't add much for name, persona, or companyId, but the incremental value on output justifies a 4.

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

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

States a specific verb ('Create a new content pipeline to automate content creation') and resource, and lists concrete output types and example user intents. It distinguishes from siblings like update_pipeline by focusing on creation. The description clearly tells an agent what this tool does and when it applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 trigger phrases ('Use when user says "set up a changelog", "create a newsletter pipeline"...') and describes the automation use case. It doesn't explicitly mention exclusions or alternatives (e.g., update_pipeline for existing pipelines), but the trigger conditions are unambiguous, so an agent can confidently select this tool for creation requests.

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

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

Annotations already signal a write/destructive operation, but the description adds meaningful context beyond them: the write-tier approval behavior, the operator_brief return value, and the instruction to always speak it rather than citing the Play by id. This is valuable behavioral disclosure that the annotations alone do not provide.

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

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

The description is well-structured and front-loaded with purpose, routing, and response expectations. It loses a point for minor redundancy: 'Speak operator_brief + deep_link; never id-alone' appears twice.

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

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

Even without an output schema, the description explains what the caller receives (operator_brief with summary/stage/next human action, plus deep_link) and what the caller must do afterward. Combined with the fully documented input schema and annotations, this is complete enough 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%, with each parameter already documented, including enum meanings. The description itself adds little parameter-level detail, so the baseline score of 3 is appropriate.

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

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

States an explicit purpose: 'Create a Playbook for the company (growth_tactics — the Plays rail)'. It also distinguishes itself from Knowledge files, clearly separating it from sibling save_knowledge rather than just restating the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'Playbook / reusable company loop → use this. SOP / guidelines / notes → save_knowledge.' It also gives timing guidance with 'Call it on the first clear ask; the card is the yes — do not re-ask in chat,' so when-to-use and when-not-to-use are both covered.

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

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

Annotations already mark this as non-read-only and destructive, and the description adds meaningful behavioral context beyond that: it only drafts, requires operator agreement before running, may need manager approval on first use, and instructs the agent not to re-ask in chat once the card is the yes. This is substantial value beyond the structured 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 compact and front-loaded: the core purpose is in the first sentence, the workflow constraint in the second, and the sensitive/approval guidance in a labeled bracket. Every sentence adds distinct value and none are redundant with the title or schema.

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

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

For a complex tool with 11 parameters and no output schema, the description covers the trigger, workflow, approval sensitivity, and the fact that the tool does not execute the play. It does not describe the return shape, but that is a minor gap given the create-draft semantics and the strong schema coverage.

Complex tools with many parameters or behaviors need more documentation. 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 82%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, and it does not clarify the two undocumented parameters (reason, linked_kr_id). Since the schema already covers most parameters well, no additional compensation is required.

Input schemas describe structure but not intent. Descriptions should explain 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+resource: 'Draft a Play (growth_tactics with steps + human review) from an oversized agent activity.' It clarifies that this tool creates a draft, not a run, and gives the trigger condition. It is clearly distinguished from run_playbook and agree_playbook by stating 'Does not run the play.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use: 'Use when a run hit step/continuation limits because the work is multi-unit.' It also explains the next step in the workflow (operator agrees via agree_playbook). It does not explicitly state when not to use it or name sibling alternatives like create_playbook, so it falls slightly short of a 5.

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

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

Beyond the annotations, the description adds meaningful behavioral context: the discount is inert until shared, automatic discounts change every checkout unprompted, and the tool is sensitive-tier with an approval nuance. There is no contradiction with the annotations; destructiveness is consistent with modifying the live Shopify store.

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

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

The description is front-loaded with the core purpose and keeps the approval guidance in a separate bracketed block. It is somewhat verbose and repeats 'never automatic discounts' in both the first sentence and the routing line, but every sentence still contributes useful operational 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?

For a create-style tool with fully documented parameters and no output schema, the description is complete enough: it covers what is created, when to use it, what not to use it for, the approval workflow, and the relevant schema is self-documenting. No essential calling information is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description only restates the 'percentage off' and 'code' concepts at a high level and adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: create a CODE discount in the connected Shopify store, with percentage-off semantics. It explicitly contrasts with automatic discounts, which distinguishes it from any related Shopify discount tooling and from sibling create_shopify_* 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?

It gives explicit when-to-use guidance ('building promotions the operator will distribute') and equally explicit when-not-to-use guidance ('never automatic discounts'). It also provides routing and approval-handling instructions, including not re-asking once the approval card is confirmed.

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

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

Annotations already mark this as a write (readOnlyHint=false, destructiveHint=true), and the description adds meaningful behavioral context: the page is never live, publishing is separately gated, and first use may require manager approval with a clear 'card is the yes' convention. There is no contradiction with the annotations.

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

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

The core behavior is front-loaded in the first sentence, and the approval/routing details are important for correct agent behavior. The 'Routing:' line is slightly redundant with the opening paragraph, which prevents a perfect score, but the description is not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 having no output schema, the description covers everything an agent needs for a correct first invocation: what the tool does, the live/draft safety model, approval behavior, and routing intent. It is complete for a simple 3-parameter 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?

The input schema already provides complete descriptions for all three parameters (title, body_html, companyId), so the description's restatement of 'title and body HTML' adds little semantic value. With 100% schema description coverage, the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: creating a new page in the connected Shopify store, and immediately adds the crucial qualifier that it is an UNPUBLISHED draft, never live. It also names the fields it sets (title and body HTML), which cleanly separates it from sibling tools like publish_shopify_page and create_shopify_product.

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

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

It provides a use context ('building out site content') and clearly states that publishing to buyers is a separate approval-gated step, so an agent knows not to expect this call to expose content live. It does not explicitly name the alternative tool for updating an existing draft or publishing, but the routing line makes the intent strongly implied.

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

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

Annotations declare the basic profile (not read-only, destructive, not idempotent), but the description adds substantial behavioral context: the draft-only constraint, the approval-gated publishing flow, and a detailed sensitive-tier approval protocol (from-now-on vs just-once approvals, 'call it on the first clear ask; the card is the yes'). This goes well beyond what annotations convey. No contradiction with annotations is 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?

The first sentence is excellent — dense and front-loaded with the core facts. But the 'Routing: Shopify: create a DRAFT product (title/description/tags) — never live' line largely repeats the first paragraph, and the approval bracket is jargon-heavy ('the card is the yes — do not re-ask in chat'). Sections are clearly delineated, but the redundancy and verbosity keep it below a 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6-param tool with no output schema and minimal annotations, the description covers the essential ground: what it does, the draft-vs-live constraint, when to invoke it, and the approval mechanics. Minor gaps remain — the return value on success (e.g., product ID) is unspecified and prerequisites such as an active Shopify connection are unstated — but the description is considerably more complete than the typical definition.

Complex tools with many parameters or behaviors need more documentation. 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 every parameter is already documented in the schema, establishing the baseline of 3. The description adds marginal grouping value by mapping 'Sets title, description, vendor, type, and tags' onto the schema parameters, but it does not deepen parameter-level semantics — no format details, no constraints, no interplay with companyId.

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

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

States a specific verb and resource — 'Create a new product in the connected Shopify store' — and adds the critical distinguishing qualifier: the result is always a DRAFT and never live. This differentiates it from siblings like publish_shopify_product, update_shopify_product_draft, and update_live_shopify_product without needing to open their schemas. It also enumerates the fields it sets (title, description, vendor, type, tags), so an agent knows exactly the scope of the call.

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

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

Gives clear usage context: 'Use when building out the catalog; the operator approves go-live later.' The 'never live — publishing to buyers is a separate approval-gated step' phrasing tells the agent this is not the go-live path and implies a publish tool exists. However, it never names that sibling alternative explicitly (publish_shopify_product) nor states when-not-to-use conditions, so it falls short of the explicit-alternatives bar.

Agents often have multiple tools that could apply. Explicit usage 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 write-tier approval note adds behavioral context not present in annotations: first-use manager approval behavior, from-now-on vs just-once semantics, and instructions on when not to re-ask. The description does not directly contradict the annotations, though destructiveHint=true is somewhat aggressive for a create 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 front-loaded with a clear one-sentence purpose, followed by a focused approval note. The note is slightly verbose but directly actionable and earns its place.

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

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

For a simple create tool with three documented parameters and no output schema, the description covers what is created, the optional headers behavior, and the approval workflow. It omits return-value details like the resulting spreadsheet ID or URL, which would help chaining, but this is not a critical gap for 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 all three parameters are already documented. The description only restates that headers are optional and adds little semantic value beyond the schema.

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

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

The first sentence names a specific verb ('Create'), a resource ('a new Google Spreadsheet), and an optional element ('optional headers'). The word 'new' clearly differentiates this from siblings that update or append to existing sheets, such as update_sheet 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 gives explicit call-time guidance: call it on the first clear ask and do not re-ask in chat once the approval card is presented. It does not explicitly name alternatives or exclusions relative to sibling tools, so it falls just short of full alternative routing guidance.

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

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

Annotations indicate destructiveHint=true, but description adds meaningful safety context: 'ALL in PAUSED state, spending nothing' and that activation is a separate human-approved step. Also explains nullcast posts are promoted-only, never on timeline. This goes beyond annotations in disclosing behavior and 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 long but dense. It front-loads the core behavior and constraints, then provides routing and approval details. A few sentences could be tightened (e.g., the sensitive-tier block is somewhat rambling), but overall each part contributes to correct 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?

Given 10 parameters, no output schema, and a complex workflow, the description covers all necessary aspects: safety (paused, no spend), copy workflow (draft_ad_variants), differentiation from platform-sibling, and approval requirements. An agent has enough to call it 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 parameter descriptions exist. The tool description adds value by explaining the relationship between ad_text and post_id (mutually exclusive), and that ad_text mints a nullcast post while post_id promotes existing post. It also notes default values indirectly (e.g., 'default 1' is in schema, but the description contextualizes them).

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

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

States a specific verb ('Create') and resource ('X ads draft') with key constraints (campaign + line item + optional ad creative, ALL in PAUSED state, spending nothing). Explicitly distinguishes from create_meta_ad_draft. The 'Distinct from create_meta_ad_draft' line differentiates it from a sibling tool.

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

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

Provides explicit routing: run draft_ad_variants first if ad copy not already picked, then create here. States intended use: 'Use when the user wants to set up or draft an X ad.' Also mentions activation is separate (set_x_ad_status), giving a when-not/alternative.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful context: the agent is soft-deleted (is_active=false), can be reactivated later, and Linnet cannot be deactivated. It also discloses the sensitive-tier approval behavior. Minor gap: it doesn't state what happens to the agent's activities or reports beyond 'ride the activity plan'.

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

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

The description is dense but well-organized: trigger phrases, soft-delete semantics, routing, and approval flow are each given their own sentence. It's longer than average but every sentence earns its place; the approval paragraph is slightly verbose but contains critical operational guidance.

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

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

For a destructive, company-scoped mutation with no output schema, the description covers the key operational concerns: how to resolve the target, what the deletion semantics are, what cannot be deleted, and how approvals work. It doesn't describe the return value, but the absence of an output schema and the presence of clear side-effect documentation make this 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 schema already documents all three parameters. The description adds context for agent_id (resolve via get_team_roster) and companyId (company-scoped), but doesn't add meaning for the optional reason parameter beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Deactivate (archive) an AI agent/specialist from the team') and lists the exact user phrasings that should trigger it. It also distinguishes itself from siblings like reactivate_agent and update_agent by clarifying the soft-delete semantics.

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

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

The description gives explicit routing instructions: resolve agent_id via get_team_roster, confirm with the user if names are similar, and notes that agent reports ride the activity plan. It also provides a clear approval-flow directive ('Call it on the first clear ask; the card is the yes — do not re-ask in chat').

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

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

The description adds meaningful behavioral context beyond the annotations: it discloses a multi-step approval pipeline with trust scoring, autopilot evaluation, skill learning, and deliverable queue progression. It also explains the split semantics and the sensitive-tier invocation etiquette. There is no contradiction with the destructiveHint=true or readOnlyHint=false annotations.

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

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

The description is dense but appropriately sized for a complex, sensitive tool with many conditional parameters. Key information is front-loaded: the main action, the pipeline side effects, the split routing, and the invocation rules. The bracketed sensitive-tier section is a little run-on but each sentence contributes useful guidance.

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

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

For a 17-parameter, no-output-schema tool, the description provides enough high-level context to understand the tool's role, side effects, split behavior, and authorization posture. The extensive per-parameter conditional logic is fully covered in the schema, so the description does not need to restate it. It lacks return-value guidance, but no output schema exists and that is not a blocker for invoking the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already carries the full semantic weight for all parameters. The description does mention the spin_off_title + spin_off_description pattern and the mixed-card routing, which aligns with the schema but does not add meaning beyond it. This matches the baseline-3 case for high schema coverage.

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

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

The description specifies a clear action (approve or deny) and resource (a Command Center card), and further explains the split behavior for mixed cards. It is not tautological and can be distinguished from read-only siblings like get_command_center_item. However, it does not name or contrast sibling decision tools, and the opening phrase omits the other decision values in the enum (snoozed, acknowledged, cancelled).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 practical when-to-use guidance: call it on the first clear ask, do not re-ask in chat, and company managers run it without a card while other members ask once. It also includes an exclusion for connector connections, noting the OAuth/connect card is still required. It does not explicitly name alternative sibling tools, but the provided context is enough for an agent to select this tool for Command Center decisions.

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