FreelanceOS

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

Annotations indicate destructiveHint=true and idempotentHint=true, which the description aligns with by describing a soft-delete that preserves data. The description adds valuable context beyond annotations: it explains what 'soft-delete' means (setting archived_at, hiding from active lists), specifies that linked projects/invoices/follow-ups remain, and mentions auditability. 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 efficiently structured in two sentences: the first explains the action and immediate effect, the second provides usage context and broader implications. Every sentence adds essential information without redundancy, making it front-loaded and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no output schema, the description does well by explaining the soft-delete mechanism, preservation of linked data, and impact on queries. However, it lacks details on error conditions (e.g., what happens if client_id doesn't exist) or confirmation of success, leaving minor gaps in completeness.

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

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

Schema description coverage is 100%, with the single parameter 'client_id' well-documented in the schema as a UUID. The description does not add any parameter-specific details beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate given the schema fully covers the parameter.

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

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

The description clearly states the specific action ('soft-delete a client by setting their archived_at timestamp') and resource ('client'), distinguishing it from siblings like clients.records.update or clients.records.get. It explicitly explains the effect ('hiding them from all active client lists while preserving their full history'), making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool ('when a freelancer is done working with a client and wants to retire the record') and contrasts it with normal queries by noting archived clients 'will no longer appear in normal queries'. It also distinguishes from destructive deletion by emphasizing preservation of data.

Agents often have multiple tools that could apply. Explicit usage 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 valuable context beyond annotations by explaining the downstream benefits of creating client records early ('saves time when creating projects and invoices later'). While annotations already indicate this is a non-readOnly, non-destructive operation, the description provides practical motivation for use. No contradiction with annotations exists.

Agents need to know what a tool does to the 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 perfectly concise with two sentences that each serve a clear purpose: the first states what the tool does, the second explains when and why to use it. There's no wasted language or unnecessary elaboration.

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

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

For a creation tool with good annotations and full schema coverage but no output schema, the description provides excellent context about usage scenarios and benefits. It could potentially mention what happens on duplicate creation attempts or error conditions, but overall it's quite complete for guiding an agent.

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

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

With 100% schema description coverage, the input schema already fully documents all 7 parameters. The description doesn't add any specific parameter details beyond what's in the schema, so it meets the baseline expectation without providing additional parameter semantics.

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

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

The description clearly states the specific action ('Create a new client record'), resource ('in the FreelanceOS database'), and distinguishes from siblings by focusing on client creation rather than archival, retrieval, or updates. It goes beyond just restating the tool name to explain the functional purpose.

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

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

The description provides explicit guidance on when to use this tool ('whenever a freelancer mentions a new client they're starting to work with or want to begin tracking') and explains the benefit ('saves time when creating projects and invoices later'). It clearly distinguishes this from sibling tools like clients.records.update or clients.records.get.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds useful context about what data is returned ('including all associated projects and follow-up communications'), which goes beyond annotations. However, it doesn't mention potential limitations like rate limits or authentication requirements.

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

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

The description is two sentences that are front-loaded with the core purpose, followed by specific usage guidelines. Every word contributes value with no wasted text, making it highly efficient and well-structured.

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

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

For a read-only, single-parameter tool with comprehensive annotations, the description provides good context about what data is returned and when to use it. However, without an output schema, it could benefit from more detail on the return format (e.g., structure of the profile). The description is mostly complete but has a minor gap in output specification.

Complex tools with many parameters or behaviors need more documentation. 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 the single parameter 'client_id' fully documented in the schema as a UUID. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the verb ('retrieve') and resource ('full profile for a single client'), specifying what data is included ('all associated projects and follow-up communications'). It distinguishes this from sibling tools like 'clients.records.list' by focusing on a single client rather than listing multiple clients.

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

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

The description explicitly states when to use this tool: 'when a freelancer asks about a specific client by name or ID' and 'when you need complete client context before drafting a proposal, invoice, or follow-up.' It implicitly distinguishes from 'clients.records.list' by focusing on single-client retrieval rather than listing multiple clients.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds valuable context about filtering (active/non-archived only) and the purpose of pagination, which goes beyond what annotations provide. No contradiction with annotations.

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

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

Two well-structured sentences: first states the core functionality with key features, second provides explicit usage guidance. Every word earns its place with zero waste 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 list operation with comprehensive annotations (read-only, idempotent, non-destructive) and full schema coverage, the description provides excellent context about filtering scope and usage scenarios. The main gap is lack of output schema, but the description compensates reasonably well by explaining what the tool returns (client lists).

Complex tools with many parameters or behaviors need more documentation. 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 fully documents all 5 parameters. The description mentions 'optional name search, sorting, and pagination' but doesn't add specific syntax or format details beyond what the schema already provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb ('List') and resource ('all active (non-archived) clients'), and distinguishes from siblings by specifying it's for active clients only (vs. archive operations). It explicitly mentions the scope of filtering and sorting capabilities.

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

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

The description provides explicit usage scenarios: 'when a freelancer wants an overview of their client roster, needs to look up a client by name, or when you need to present a list of clients for the user to choose from.' This gives clear context for when to use this tool versus alternatives like get or create operations.

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

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

The description adds valuable behavioral context beyond annotations: it clarifies that 'only the fields you provide will be changed, all others remain untouched' (partial update behavior) and provides real-world use cases. While annotations cover idempotency and non-destructive nature, the description enhances understanding of the update semantics without contradicting annotations.

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

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

The description is efficiently structured in two sentences: the first states the core purpose, the second provides usage guidance and behavioral clarification. Every word earns its place with no redundancy or fluff, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 update tool with 8 parameters, 100% schema coverage, and comprehensive annotations, the description provides excellent context about when to use it and how it behaves. The main gap is the lack of output schema information (what the tool returns), but given the annotations and parameter documentation, the description is largely complete for agent usage.

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

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

With 100% schema description coverage, the input schema already documents all 8 parameters thoroughly. The description doesn't add specific parameter details beyond what's in the schema, but it does reinforce the partial update concept ('only the fields you provide will be changed'). This meets the baseline expectation when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Update one or more fields'), the resource ('existing client record'), and provides specific examples of what can be modified (contact details, billing rate, notes). It distinguishes this tool from sibling tools like clients.records.create (for new records) and clients.records.get (for reading).

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

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

The description explicitly states 'Use this tool when a freelancer wants to correct contact details, change a billing rate, update notes, or make any other modification to a client's stored information.' This provides clear guidance on when to use this tool versus alternatives like clients.records.create (for new clients) or clients.records.get (for reading only).

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds valuable context about what data is fetched (invoices, follow-up history, contact details) and the purpose (to inform follow-up drafting), which goes beyond the annotations. No contradiction with annotations exists.

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

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

The description is efficiently structured in two sentences: the first states the purpose and scope, the second provides crucial usage guidance. Every sentence earns its place with no wasted words, and key information is front-loaded.

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

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

For a read-only context-fetching tool with good annotations and 100% schema coverage, the description provides sufficient context about what data is retrieved and when to use it. The main gap is the lack of output schema, but the description compensates by specifying the types of context returned. It could be more complete by mentioning response format or data structure.

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

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

Schema description coverage is 100%, with both parameters (client_id and project_id) well-documented in the schema. The description mentions 'client' context but doesn't add specific parameter details beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting for parameter documentation.

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

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

The description clearly states the specific action ('fetch all relevant context') and resource ('for a client'), and distinguishes this from sibling tools by specifying it's for follow-up drafting context rather than direct followup creation or other client operations. It explicitly mentions what context is included: outstanding invoices, recent follow-up history, and client contact details.

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

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

The description provides explicit usage guidance with 'Always call this tool before followups.create so the drafted message is informed by the client's current account status.' This clearly indicates when to use this tool (before creating follow-ups) and references a specific alternative tool (followups.create) for the next step in the workflow.

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

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

Annotations already indicate this is a non-readOnly, non-destructive operation (readOnlyHint: false, destructiveHint: false). The description adds useful context about the tool's purpose (storing drafted messages for tracking) and timing (before or after sending), but doesn't provide additional behavioral details like authentication requirements, rate limits, or what happens on duplicate submissions. No contradiction with annotations exists.

Agents need to know what a tool does to the 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 perfectly concise with two sentences that directly address the tool's purpose and usage context. Every word earns its place, and the information is front-loaded with no unnecessary verbiage 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 creation tool with good annotations (non-destructive, non-readOnly) and comprehensive parameter documentation (100% schema coverage), the description provides adequate context about what the tool does and when to use it. The main gap is the lack of output schema, but the description doesn't need to explain return values. It could benefit from mentioning what happens after storage (e.g., returns a message ID), but it's reasonably complete for its complexity level.

Complex tools with many parameters or behaviors need more documentation. 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, all parameters are well-documented in the input schema. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. The baseline score of 3 is appropriate when the schema carries the full parameter documentation burden.

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

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

The description clearly states the specific action ('Store a drafted follow-up message'), the resource ('in the FreelanceOS database'), and the purpose ('for tracking purposes before or after sending it to the client'). It distinguishes from sibling tools like followups.messages.get/list/update by focusing on creation/storage rather than retrieval or modification.

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

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

The description provides clear context for when to use this tool: 'when the freelancer has composed a follow-up and wants to save it for tracking purposes before or after sending it to the client.' It doesn't explicitly mention when NOT to use it or name specific alternatives, but the context is sufficient for an agent to understand its primary use case.

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

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

Annotations already provide strong behavioral hints (readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false), indicating this is a safe, read-only, deterministic operation. The description adds useful context by specifying what details are returned ('content, type, and sent status'), which isn't covered by annotations. However, it doesn't mention error cases (e.g., invalid ID) or rate limits, leaving some behavioral aspects unclear.

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

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

The description is two sentences, both essential: the first states the purpose, and the second provides usage guidelines. It is front-loaded with the core functionality and wastes no words. Every sentence earns its place by adding distinct value.

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

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

Given the tool's low complexity (single parameter, no output schema) and rich annotations (covering safety and idempotency), the description is largely complete. It clarifies the tool's purpose, usage, and return details. However, without an output schema, it could more explicitly describe the return structure (e.g., JSON fields), though the mention of 'content, type, and sent status' partially addresses this.

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

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

Schema description coverage is 100%, with the parameter 'followup_id' fully documented in the schema as a UUID. The description adds no additional parameter semantics beyond what's in the schema (e.g., no examples or format clarifications). According to guidelines, when schema coverage is high (>80%), the baseline score is 3 even without param info in the description, which applies here.

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

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

The description clearly states the verb ('Retrieve') and resource ('a single follow-up record by its unique ID'), making the purpose specific. It distinguishes this tool from sibling tools like 'followups.messages.list' (which retrieves multiple records) and 'followups.messages.create' (which creates new records), providing clear differentiation.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer asks to view the full details of a specific saved follow-up, including its content, type, and sent status.' This provides clear context for usage and implicitly distinguishes it from list operations (for multiple records) or create/update operations. It directly addresses the agent's decision-making needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds useful context about pagination support and filtering capabilities, but doesn't provide additional behavioral details like rate limits, authentication requirements, or what happens with empty results.

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

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

The description is efficiently structured in two sentences: the first states the core functionality with key features, the second provides explicit usage guidelines. Every word serves a purpose with no redundancy or unnecessary elaboration.

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

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

For a read-only list tool with comprehensive annotations and full schema coverage, the description provides good contextual completeness. It covers purpose, usage scenarios, and key capabilities. The main gap is the lack of output schema, leaving return format unspecified, but the description compensates reasonably given the tool's straightforward nature.

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

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

With 100% schema description coverage, the input schema fully documents all 8 parameters. The description mentions filtering and pagination support, which aligns with parameters like 'sent', 'type', 'limit', and 'offset', but doesn't add meaningful semantic information beyond what's already in the schema descriptions.

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

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

The description clearly states the tool's purpose with specific verbs ('list and filter follow-up records') and resources ('for a client or project'), and distinguishes it from siblings like followups.messages.create or followups.messages.update by focusing on retrieval rather than creation or modification.

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

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

The description explicitly states when to use this tool: 'when the freelancer asks to review follow-up history, check outstanding drafts, or audit all sent communications for a given client.' It provides concrete scenarios that guide the agent toward appropriate invocation contexts.

Agents often have multiple tools that could apply. Explicit usage 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 valuable context about the tool's purpose (revising drafts before sending) that isn't captured in annotations. While annotations provide structural hints (idempotent, not read-only, not destructive), the description clarifies the workflow context. No contradiction with annotations exists.

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

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

Two sentences with zero waste. The first sentence states the tool's purpose and scope, the second provides clear usage guidance. Every word contributes to understanding the tool's function and appropriate use.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 good annotations and full parameter documentation, the description provides excellent workflow context. The main gap is the lack of output schema, but the description compensates well by explaining the tool's purpose in the freelancer workflow. It could be slightly more complete by mentioning what happens to unspecified fields.

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

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

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description mentions the same fields (subject, body, type, project association) but doesn't add significant semantic value beyond what's in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Update'), target resource ('existing follow-up record'), and specific fields that can be modified ('content or metadata', 'subject, body, type, or project association'). It distinguishes this from sibling tools like 'followups.messages.create' by specifying it's for revising existing records.

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

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

The description provides explicit usage context: 'Use when the freelancer wants to revise a drafted follow-up's subject, body, type, or project association before sending it to the client.' This clearly indicates when this tool should be used versus alternatives like creating new follow-ups or working with sent follow-ups.

Agents often have multiple tools that could apply. Explicit usage 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 valuable behavioral context beyond what annotations provide. While annotations indicate this is a non-destructive, idempotent mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description clarifies that this tool records a timestamp and triggers a state transition from draft to sent. This explains the operational effect that annotations alone don't convey. No contradiction with annotations exists.

Agents need to know what a tool does to the 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 perfectly concise and well-structured in two sentences. The first sentence explains what the tool does, and the second provides clear usage guidance. Every word serves a purpose with zero redundancy or unnecessary elaboration.

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

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

For a single-parameter mutation tool with good annotations but no output schema, the description provides excellent context about the tool's purpose and usage. It explains the state transition effect that annotations don't cover. The only minor gap is not explicitly mentioning what happens on success (e.g., whether it returns confirmation), but given the annotations and clear behavioral description, this is acceptable.

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

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

With 100% schema description coverage, the input schema already fully documents the single required parameter (followup_id as a UUID). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation without exceeding it.

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

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

The description clearly states the specific action ('Record the current timestamp as the sent date') on a specific resource ('on a follow-up'), with explicit mention of the state transition ('transitioning it from draft to sent status'). It distinguishes this tool from sibling tools like followups.messages.create or followups.messages.update by focusing on marking a follow-up as sent rather than creating or editing message content.

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

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

The description provides explicit guidance on when to use this tool: 'Use when the freelancer confirms they have actually sent the follow-up message to the client outside of FreelanceOS.' This clearly defines the triggering condition and distinguishes it from tools that might send messages within the system or handle draft creation.

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

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

Annotations already declare this is a write operation (readOnlyHint=false) and non-destructive, so the description doesn't need to repeat those safety aspects. The description adds useful context about persistence ('persist a new invoice') and the business purpose ('billable invoice'), but doesn't disclose additional behavioral traits like authentication requirements, rate limits, or what happens on duplicate invoice numbers.

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

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

The description consists of two focused sentences: one stating the tool's purpose and one providing usage guidance. Every word serves a clear function with zero waste. It's appropriately sized and front-loaded with the core functionality.

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

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

For a creation tool with comprehensive schema documentation (100% coverage) and clear annotations, the description provides adequate context about what the tool does and when to use it. The main gap is the absence of an output schema, but the description doesn't need to explain return values. It could benefit from mentioning prerequisites or constraints beyond what's in the schema.

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

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

With 100% schema description coverage, the input schema already comprehensively documents all 13 parameters. The description mentions 'line items, tax, and totals' which aligns with some parameters but doesn't add meaningful semantic context beyond what the schema provides. The baseline score of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Create and persist a new invoice'), the resource ('invoice with line items, tax, and totals'), and the system context ('FreelanceOS database'). It distinguishes this from sibling tools like invoices.records.get/list/update by specifying creation rather than retrieval or modification.

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

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

The description provides clear context for when to use this tool: 'when the freelancer wants to generate and save a billable invoice for a completed or ongoing project.' This gives practical guidance but doesn't explicitly mention when NOT to use it or name specific alternative tools for related scenarios.

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

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

The description adds valuable context beyond annotations by specifying that it retrieves 'full details' of an invoice. While annotations already indicate this is a read-only, non-destructive, idempotent operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true), the description clarifies the scope of data returned. No contradiction with annotations exists.

Agents need to know what a tool does to the 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 perfectly concise with two sentences: the first states the core functionality, the second provides usage guidance. Every word earns its place with zero redundancy or unnecessary elaboration.

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

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

For a simple read operation with comprehensive annotations and full schema coverage, the description provides adequate context. It could be slightly more complete by mentioning what 'full details' includes or noting the absence of an output schema, but it effectively guides usage for this straightforward 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?

With 100% schema description coverage, the input schema already fully documents the single required parameter (invoice_id with UUID format and ownership constraints). The description mentions 'by its UUID' which aligns with but doesn't add meaningful semantic value beyond what's in the schema description 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 clearly states the specific action ('Retrieve the full details'), resource ('a single invoice'), and identifier mechanism ('by its UUID'). It distinguishes this tool from its sibling 'invoices.records.list' which would retrieve multiple invoices rather than a specific one.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer asks to view, review, or share the details of a specific invoice.' This provides clear context for invocation and differentiates it from list operations or other invoice-related tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety aspects. The description adds valuable behavioral context beyond annotations: it specifies pagination behavior ('paginated'), filtering capabilities ('filtered list'), and user scope ('for the authenticated freelancer'), which are not captured in 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 two sentences with zero waste: the first states the core functionality, and the second provides usage guidance. It's front-loaded with the primary purpose and efficiently structured.

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

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

Given the annotations cover safety (read-only, non-destructive, idempotent) and the schema fully describes parameters, the description adds good context on usage scenarios and behavioral traits like pagination. However, without an output schema, it doesn't describe return values (e.g., what fields are included in invoice records), leaving 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 fully documents all 9 parameters. The description mentions filtering and date ranges generally but doesn't add specific parameter semantics beyond what's already in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Return a paginated, filtered list of invoices') and resource ('for the authenticated freelancer'), distinguishing it from sibling tools like invoices.records.get (single invoice) and invoices.records.create (creation). It explicitly identifies the target user context.

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

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

The description provides explicit guidance on when to use this tool: 'when the freelancer asks about outstanding, paid, overdue, or draft invoices, or wants a revenue summary for a date range.' This gives clear scenarios for invocation without needing to reference 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 adds valuable behavioral context beyond the annotations. While annotations indicate this is a non-destructive, idempotent mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description clarifies that it updates 'existing invoice' fields and provides real-world use cases. It doesn't contradict annotations and adds practical application context.

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

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

The description is perfectly concise with two sentences: the first states the core functionality, the second provides usage examples. Every word earns its place with no redundancy or filler content. It's front-loaded with the essential information.

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

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

For a mutation tool with 11 parameters and no output schema, the description provides good context about when to use it and what it does. The annotations cover safety aspects (non-destructive, idempotent), and the schema has full parameter documentation. The main gap is lack of information about return values or error conditions, but overall it's 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?

With 100% schema description coverage, the input schema already provides comprehensive parameter documentation. The description mentions 'fields' like status, financial totals, line items, and due date, but doesn't add significant semantic value beyond what's already in the schema descriptions. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('update one or more fields on an existing invoice') and resource ('invoice'), distinguishing it from sibling tools like invoices.records.create (for new invoices) and invoices.records.get/list (for reading). It provides concrete examples of fields that can be updated, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool with specific scenarios: 'when the freelancer marks an invoice as sent, records a payment, corrects line items, or changes the due date.' This provides clear contextual guidance for when this update operation is appropriate versus other invoice operations.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true, which the description aligns with by explaining it's a soft-delete that preserves data. The description adds valuable context beyond annotations: it clarifies that archiving hides the project from active lists (behavioral effect) and preserves historical data (safety aspect), though it doesn't mention rate limits or auth needs. 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 two sentences, front-loaded with the core action and effect, followed by usage guidance. Every sentence adds value: the first explains what the tool does and its impact, the second provides context for when to use it. No wasted words or redundancy.

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

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

Given the tool's complexity (destructive mutation with idempotency), annotations cover key behavioral traits (destructive, idempotent), and the description adds context on soft-delete effects and usage. However, there is no output schema, and the description doesn't specify return values or error conditions, leaving a minor gap in completeness 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%, with the parameter 'project_id' well-documented in the schema as a UUID. The description does not add any parameter-specific details beyond what the schema provides, such as format examples or constraints. Baseline score of 3 is appropriate since the schema carries the full parameter documentation burden.

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

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

The description clearly states the specific action ('soft-delete a project by setting its archived_at timestamp') and the resource ('project'), distinguishing it from siblings like projects.records.create or projects.records.update. It explains the effect ('hiding it from all active project lists while preserving all historical data'), making the purpose explicit and distinct.

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

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

The description explicitly states when to use this tool: 'when a freelancer wants to close out a completed or cancelled project without permanently destroying its records.' This provides clear context for usage, distinguishing it from permanent deletion alternatives (though not named) and indicating it's for archiving rather than active management.

Agents often have multiple tools that could apply. Explicit usage 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 this is a write operation (readOnlyHint: false) that is not idempotent or destructive. The description adds context about persistence to the database and the project lifecycle tracking purpose, but doesn't disclose additional behavioral traits like error conditions, authentication requirements, or rate limits. With annotations covering basic safety, the description adds some value but not rich behavioral context.

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

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

The description is two sentences that efficiently convey purpose and usage guidelines. Every word earns its place - the first sentence states what the tool does, and the second sentence provides clear usage context. No wasted words or redundant 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 creation tool with good annotations (readOnlyHint: false, destructiveHint: false) and comprehensive schema coverage, the description provides adequate context about when to use it and what it accomplishes. The main gap is the lack of output schema, but the description doesn't need to explain return values. It could benefit from mentioning error conditions or success criteria.

Complex tools with many parameters or behaviors need more documentation. 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 well-documented in the schema itself. The description mentions 'budget, timeline, and status' which aligns with parameters like budget, start_date, end_date, but doesn't add meaningful semantic information beyond what the schema already provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('Create a new project'), the resource ('linked to an existing client'), and the system ('persist it to the FreelanceOS database'). It distinguishes from sibling tools like 'projects.records.update' or 'projects.records.archive' by specifying creation rather than modification or archival.

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

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

The description explicitly states when to use this tool: 'when a freelancer is starting new work for a client and needs to track budget, timeline, and status across the project lifecycle.' This provides clear context for usage and distinguishes it from alternatives like updating existing projects or creating other records (e.g., invoices or proposals).

Agents often have multiple tools that could apply. Explicit usage 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 this is a read-only, non-destructive, idempotent operation with a closed-world assumption. The description adds useful context about what data is included (client name and contact information), which isn't covered by annotations. However, it doesn't mention potential errors (e.g., if the project_id doesn't exist) or response format details.

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

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

The description is two sentences that are front-loaded with the tool's purpose and followed by clear usage guidance. Every word contributes value with no redundancy or unnecessary 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 simple read operation with comprehensive annotations (readOnlyHint, idempotentHint, etc.) and a fully documented single parameter, the description provides good context about what data is returned and when to use it. The main gap is the lack of an output schema, but the description partially compensates by specifying included data fields.

Complex tools with many parameters or behaviors need more documentation. 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, with the 'project_id' parameter fully documented as a UUID. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the specific action ('Retrieve full details'), resource ('a single project'), and scope ('including the associated client name and contact information'). It distinguishes this tool from sibling tools like 'projects.records.list' (which retrieves multiple projects) and 'projects.records.get' (which is this tool itself).

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

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

The description provides explicit guidance on when to use this tool: 'when a freelancer asks about a specific project's status, budget, or timeline.' This clearly differentiates it from 'projects.records.list' (for listing multiple projects) and other tools like 'projects.records.update' (for modifying projects).

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds useful context about filtering out archived projects and the tool's purpose for freelancer portfolio overview, but doesn't disclose additional behavioral traits like rate limits, authentication requirements, or response format details.

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

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

The description is perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does with its key features, and the second provides usage guidance. There's no wasted language 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 list operation with comprehensive annotations and full schema coverage, the description provides adequate context about purpose and usage. The main gap is the lack of output schema, so the description doesn't explain what format the results will be in, but given the tool's relative simplicity and good annotations, this is a minor omission.

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

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

With 100% schema description coverage, the input schema already comprehensively documents all 7 parameters. The description mentions 'optional full-text search, status and client filters, sorting, and pagination' which aligns with the schema but doesn't add significant semantic value beyond what's already in the parameter descriptions.

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

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

The description clearly states the verb ('List') and resource ('all non-archived projects') with specific scope. It distinguishes from sibling tools like 'projects.records.archive' by explicitly mentioning 'non-archived' and from 'projects.records.get' by indicating it returns multiple records with filtering capabilities.

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

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

The description provides clear usage context ('when a freelancer wants an overview of their work portfolio or needs to locate a specific project by name or client'), which helps the agent understand when to invoke this tool. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings.

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

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

The description adds valuable behavioral context beyond annotations: it clarifies that you can update 'one or more fields' (partial updates allowed) and lists specific fields that can be modified. Annotations already cover idempotentHint=true (safe for retries) and destructiveHint=false (non-destructive), but the description provides practical usage context. No contradictions with annotations exist.

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

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

The description is perfectly structured in two sentences: the first states the core functionality, the second provides usage guidelines. Every word earns its place with zero redundancy. It's front-loaded with the main purpose and efficiently conveys essential information.

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

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

For a mutation tool with rich annotations (idempotent, non-destructive) and full schema coverage, the description provides adequate context. It explains the tool's purpose, usage scenarios, and partial update capability. The main gap is lack of output information (no output schema), but the description compensates reasonably given the annotations' safety assurances.

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

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

With 100% schema description coverage, the input schema already fully documents all 8 parameters. The description lists some parameter examples ('name, description, budget, dates, or lifecycle status') but doesn't add meaningful semantic information beyond what's in the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Update one or more fields on an existing project record') and enumerates the key resources that can be modified ('name, description, budget, dates, or lifecycle status'). It distinguishes this tool from sibling tools like projects.records.create (for new records) and projects.records.get/list (for reading).

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

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

The description explicitly states when to use this tool: 'when a freelancer wants to edit project details, revise the budget, adjust the timeline, or mark a project as paused or completed.' It provides concrete scenarios (editing details, budget revision, timeline adjustment, status changes) that guide appropriate usage without mentioning alternatives, which is sufficient given the clear sibling differentiation.

Agents often have multiple tools that could apply. Explicit usage 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 valuable behavioral context beyond annotations: it specifies that this is an 'atomic operation' (implying transactional consistency), mentions automatic seeding of scope_definitions, and indicates it's triggered by client acceptance. Annotations cover idempotency and non-destructive aspects, but the description enriches this with operational details without contradiction.

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

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

The description is front-loaded with the core action and scope, followed by usage guidance in a second sentence. Every sentence earns its place by providing essential operational and contextual information without redundancy or fluff.

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

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

Given the tool's complexity (atomic operation with side effects), the description is mostly complete: it explains the action, timing, and automatic seeding. However, without an output schema, it lacks details on return values (e.g., success confirmation or error handling). Annotations provide safety hints, but the description could be slightly enhanced for full completeness.

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

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

The description does not explicitly mention the 'proposal_id' parameter. However, with 100% schema description coverage (the schema fully documents the parameter as a UUID for the proposal), the baseline is 3. The description implies the parameter through context but adds no additional semantic meaning beyond what the schema provides.

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

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

The description clearly states the specific action ('Mark a proposal as accepted'), the resource ('proposal'), and the scope of operations ('record the response timestamp, and automatically seed the linked project's scope_definitions from the proposal deliverables in a single atomic operation'). It distinguishes from siblings like proposals.records.update by focusing on acceptance rather than general updates.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer confirms that a client has accepted the proposal and work is ready to begin.' This provides clear context for invocation, distinguishing it from other proposal-related tools that might handle creation, listing, or updates without acceptance.

Agents often have multiple tools that could apply. Explicit usage 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 this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context about persistence to a database and tracking/future reference, which is useful but doesn't disclose behavioral traits like authentication needs, rate limits, or what happens on duplicate proposals. No contradiction with annotations exists.

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

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

The description is two sentences: the first states the purpose and key details, the second provides usage guidelines. Every word earns its place with no redundancy, and it's front-loaded with the core action. It efficiently conveys necessary information without fluff.

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

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

For a creation tool with no output schema, the description is reasonably complete: it explains the purpose, usage context, and key parameters. However, it doesn't detail the return value or potential errors, which could be helpful given the mutation nature. Annotations cover safety aspects, but more behavioral context (e.g., idempotency hints) would enhance completeness.

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

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

Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description mentions 'title, deliverables, pricing, and expiry date' which map to parameters like title, content, amount, and valid_until, but doesn't add meaning beyond what the schema provides (e.g., explaining relationships between parameters). Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the action ('Store a new proposal'), the resource ('for a project'), and captures specific details ('title, deliverables, pricing, and expiry date'). It distinguishes this tool from sibling tools like proposals.records.get, proposals.records.list, and proposals.records.update by emphasizing creation/persistence rather than retrieval or modification.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer has drafted proposal content and wants to persist it to the database for tracking and future reference.' This provides clear context about the prerequisite (drafted content) and purpose (persistence for tracking/reference), differentiating it from update or retrieval operations among siblings.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying what fields are returned ('all stored fields including status, amount, and content'), which isn't covered by annotations. However, it doesn't mention potential error conditions or authentication requirements.

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

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

The description is two sentences that are front-loaded with purpose and usage guidance. Every word serves a clear function: the first sentence explains what the tool does and what it returns, while the second provides explicit invocation context. There's no wasted verbiage.

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

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

For a simple read operation with comprehensive annotations and a fully described single parameter, the description provides good context about what fields are returned and when to use it. The main gap is the lack of output schema, but the description partially compensates by mentioning specific returned fields. It doesn't cover error cases or response format details.

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

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

Schema description coverage is 100%, with the single parameter 'proposal_id' fully documented in the schema as a UUID. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the action ('Retrieve a single proposal'), specifies the resource ('by its unique identifier'), and indicates the scope ('returning all stored fields including status, amount, and content'). It distinguishes from sibling tools like 'proposals.records.list' by focusing on single-record retrieval rather than listing multiple proposals.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer asks to view, review, or reference the details of a specific proposal.' This provides clear context for invocation and differentiates it from alternatives like 'proposals.records.list' for browsing multiple proposals or 'proposals.records.update' for modifying proposals.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds useful context about filtering capabilities (project, client, status) and pagination support, but doesn't disclose behavioral details like rate limits, authentication requirements, or what happens with invalid filters. With annotations covering core safety traits, the description adds moderate value.

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

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

The description is two sentences: the first states the core functionality with key features, and the second provides specific usage scenarios. Every word earns its place—no fluff, no repetition, and the most important information (what the tool does) is front-loaded. It's efficiently structured for quick 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 read-only listing tool with 100% schema coverage and comprehensive annotations, the description provides good contextual completeness. It explains the tool's purpose, when to use it, and key capabilities. The main gap is the lack of an output schema, so the description doesn't clarify what the returned data looks like (e.g., fields in each proposal record), but given the annotations and schema richness, this is a minor omission.

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

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

Schema description coverage is 100%, with all 7 parameters well-documented in the schema itself. The description mentions filtering by 'project, client, or status' and 'sorting and pagination', which aligns with parameters like project_id, client_id, status, sort_by, sort_dir, limit, and offset. However, it doesn't add meaningful semantic details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('proposals'), specifies filtering criteria ('by project, client, or status'), and mentions additional capabilities ('sorting and pagination'). It distinguishes this tool from sibling proposal tools like 'proposals.records.create', 'proposals.records.update', and 'proposals.records.accept' by focusing on listing/filtering rather than creating, modifying, or accepting proposals.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides three concrete scenarios for when to use this tool: 'when the freelancer asks for proposal history', 'wants to audit outstanding proposals', or 'needs to check the status of proposals sent to a client.' This gives clear guidance on appropriate contexts without needing to mention specific alternatives since the tool's purpose (filtered listing) is distinct from other proposal operations.

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

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

Annotations provide readOnlyHint=false (mutation), destructiveHint=false (non-destructive), and idempotentHint=true. The description adds valuable context about use cases (revising details, marking as sent, recording responses) and clarifies this is for partial updates rather than full replacement. No contradiction with annotations.

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

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

Two sentences with zero waste. First sentence states purpose and scope, second provides explicit usage guidelines. Every word earns its place with clear front-loaded 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 mutation tool with 9 parameters, the description provides excellent purpose and usage context. Annotations cover safety profile (non-destructive, idempotent). The main gap is no output schema, but the description compensates well with clear behavioral context. Could slightly improve by mentioning partial update nature more explicitly.

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

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

Schema description coverage is 100%, so each parameter is well-documented in the schema. The description mentions general field categories (content, pricing, status, timestamps) but doesn't add specific semantic details beyond what the schema already provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the action ('update one or more fields'), resource ('existing proposal'), and scope ('including content, pricing, status, or key timestamps'). It distinguishes from sibling tools like proposals.records.accept by specifying this is for revisions rather than full acceptance flow.

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

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

Explicitly states when to use: 'when the freelancer wants to revise proposal details, mark it as sent, or record a client response without going through the full accept flow.' It distinguishes from proposals.records.accept by mentioning the alternative path for client responses.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds useful context about pagination behavior ('configurable sort order') and filtering options, but doesn't mention rate limits, authentication needs, or what specific data fields are returned.

Agents need to know what a tool does to the 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 perfectly front-loaded with the core purpose in the first sentence, followed by specific usage guidelines. Both sentences earn their place with zero wasted words, making it highly efficient and 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 read-only list tool with excellent annotations and full schema coverage, the description provides good contextual completeness with clear purpose and usage guidelines. The main gap is the lack of output schema, but the description compensates reasonably well given the tool's straightforward nature.

Complex tools with many parameters or behaviors need more documentation. 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 all parameters well-documented in the schema itself. The description mentions 'optional filtering by classification and configurable sort order' which aligns with the schema but doesn't add significant semantic value beyond what's already provided in the structured fields.

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

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

The description clearly states the specific action ('List all scope change requests') with the target resource ('logged against a project'), and distinguishes it from siblings by specifying its unique filtering and sorting capabilities for scope changes, unlike other list tools for clients, projects, etc.

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

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

The description explicitly provides three concrete use cases ('when reviewing scope creep history, preparing a change-order summary, or auditing out-of-scope requests for billing'), giving clear guidance on when this tool should be selected over 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 adds valuable behavioral context beyond what annotations provide. While annotations indicate this is a mutable operation (readOnlyHint: false) that's not destructive, the description clarifies this is for 'recording' and 'maintaining an auditable history,' suggesting it creates persistent records. It doesn't mention rate limits or authentication needs, but adds meaningful operational context.

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

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

The description is perfectly concise with two sentences that each serve distinct purposes: the first states the tool's purpose, the second provides critical usage guidance. There's zero wasted language, and the most important constraint is front-loaded in the second sentence.

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

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

For a creation/mutation tool with no output schema, the description provides excellent context about when to use it and its purpose. It could mention what happens after logging (e.g., whether it triggers notifications or appears in reports) but covers the essential operational constraints well given the annotations and 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?

With 100% schema description coverage, the schema already documents all 6 parameters thoroughly. The description doesn't add specific parameter semantics beyond what's in the schema, so it meets the baseline expectation without providing extra value.

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

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

The description clearly states the specific action ('Record a client scope change request') and purpose ('to maintain an auditable history of scope creep'). It distinguishes this tool from siblings like scope.changes.list (which lists changes) and scope.definition.* tools (which manage scope 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?

The description provides explicit usage instructions: 'Use this tool ONLY after the freelancer confirms they want to log the change — never log speculatively without explicit instruction.' This gives clear when-to-use guidance and establishes a prerequisite condition for invocation.

Agents often have multiple tools that could apply. Explicit usage 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 this is a read-only, non-destructive, idempotent operation. The description adds valuable context beyond annotations: it explains that the tool retrieves both the scope definition and change history for assessment purposes, which helps the agent understand the behavioral intent and output structure, though it doesn't detail rate limits or auth needs.

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

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

The description is two sentences with zero waste: the first states the purpose, and the second provides usage guidelines. It's front-loaded with essential information and appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity, rich annotations (readOnlyHint, idempotentHint, etc.), and 100% schema coverage, the description is mostly complete. It explains the tool's purpose and usage well, but lacks details on output format or error handling, which could be useful since there's no output schema.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal semantic context by mentioning 'project' and 'new client request,' which aligns with parameters but doesn't provide additional syntax or format details beyond what's in the schema, meeting 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?

The description clearly states the tool's purpose: 'Retrieve the agreed scope definition and full change history for a project' (specific verb+resource). It distinguishes from siblings like 'scope.definition.get' by adding the purpose of assessing new requests against scope, making it distinct in functionality.

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

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

The description explicitly states when to use this tool: 'Use this tool when a client asks for something new and the freelancer wants an informed opinion on whether it is in scope before responding.' It provides clear context and a specific scenario, with no need for alternatives since it's uniquely focused on scope assessment.

Agents often have multiple tools that could apply. Explicit usage 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 this is a non-readOnly, non-destructive, non-idempotent creation operation. The description adds valuable context by specifying this is for 'persisting' scope definitions and establishing 'shared understanding,' which implies this is a formal record-keeping step. It doesn't mention permissions, rate limits, or error conditions, but provides useful behavioral context beyond annotations.

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

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

The description is two sentences with zero waste. The first sentence states the purpose, and the second provides clear usage guidelines. Every word earns its place, and the information is front-loaded with the core function.

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

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

For a creation tool with good annotations and full schema coverage, the description provides excellent purpose and usage context. The main gap is lack of output information (no output schema), but the description compensates somewhat by indicating this 'persists' scope definitions. It could mention what happens on success/failure, but is reasonably complete given the structured data available.

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

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

With 100% schema description coverage, the schema already documents all 5 parameters thoroughly. The description mentions 'deliverables, boundaries, and exclusions' which aligns with parameter names but doesn't add semantic meaning beyond what the schema provides. The baseline score of 3 reflects adequate parameter documentation through the schema alone.

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

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

The description clearly states the verb ('Define and persist') and resource ('agreed project scope with deliverables, boundaries, and exclusions'), making the purpose specific. It distinguishes from sibling tools like 'scope.definition.get' or 'scope.definition.update' by focusing on initial creation rather than retrieval or modification.

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

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

The description explicitly states when to use this tool: 'when starting a new project or immediately after a proposal is accepted by the client.' It provides clear context for usage, distinguishing it from other scope-related tools that might be used later in the project lifecycle.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable context about retrieving the 'current active' scope definition, which implies it returns the latest approved version rather than historical data. However, it doesn't mention potential errors (e.g., if project doesn't exist) or authentication requirements.

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

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

Two sentences that are front-loaded with the core purpose followed by specific usage guidance. Every word earns its place with no redundancy or fluff. The structure efficiently communicates both what the tool does and when to use it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with comprehensive annotations and a simple single-parameter schema, the description provides good context about what's retrieved and when to use it. The main gap is lack of output information (no output schema), but the description compensates somewhat by listing what's included in the scope definition. Could be more complete by mentioning response format or error cases.

Complex tools with many parameters or behaviors need more documentation. 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 the single parameter 'project_id' well-documented in the schema as a UUID. The description doesn't add any additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the verb 'retrieve' and the resource 'current active scope definition for a project', specifying what it includes (deliverables, boundaries, assumptions, exclusions). It distinguishes from siblings like scope.definition.create/update by focusing on retrieval rather than modification.

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

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

Explicitly states when to use: 'when the freelancer wants to review exactly what was agreed with the client before starting work or answering a scope question.' This provides clear context for usage and implicitly distinguishes from other scope tools like scope.changes.list or scope.definition.check.

Agents often have multiple tools that could apply. Explicit usage 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 this is a mutable (readOnlyHint: false), idempotent, non-destructive operation. The description adds valuable context about the 'mutually agreed' prerequisite, which isn't captured in annotations. However, it doesn't mention rate limits, authentication needs, or error conditions, leaving some behavioral aspects uncovered.

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

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

Two concise sentences that are front-loaded with the core purpose and followed by usage context. Zero wasted words—every phrase adds value (e.g., 'mutually agreed' clarifies prerequisites).

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 purpose, usage context, and prerequisites well. Annotations provide safety and idempotency info. However, it doesn't describe what happens on success/failure or return values, leaving some gaps for an agent invoking 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 all parameters are documented in the schema itself. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain format or constraints for boundaries, exclusions, etc.). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the action ('update one or more fields'), the target ('active scope definition for a project'), and distinguishes it from siblings like scope.definition.create (for initial creation) and scope.definition.get (for retrieval). It specifies 'mutually agreed' context, which adds precision beyond a generic update.

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

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

Explicitly states when to use: 'when the client and freelancer have mutually agreed to change the scope and the persisted record needs to reflect the new agreement.' This provides clear context for invocation and implicitly distinguishes from scope.definition.create (initial setup) and scope.definition.get (viewing).

Agents often have multiple tools that could apply. Explicit usage 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 this is a read-only, non-destructive, idempotent operation with a closed world. The description adds valuable context about the aggregation scope (total minutes/hours over a date range) and the optional billable filtering, which goes beyond what annotations provide. No contradictions exist.

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

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

The description is perfectly concise with two sentences: one stating the core functionality and another providing three specific use cases. Every word earns its place, and the structure is front-loaded with the primary purpose.

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

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

Given the tool's moderate complexity (aggregation with filtering), rich annotations covering safety and behavior, and full parameter documentation, the description provides excellent context about when and why to use it. The only minor gap is the lack of output schema, but the description adequately conveys the return value concept (total minutes/hours).

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

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

With 100% schema description coverage, the schema already fully documents all four parameters. The description mentions 'optional date range' and 'billable hours' contextually, but doesn't add significant semantic detail beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('calculate total minutes and hours') and resources ('logged against a project'), and distinguishes it from sibling tools like time.entries.list or time.entries.get by focusing on aggregation rather than listing individual entries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides three concrete use cases: 'preparing an invoice, verifying billable hours before sending to a client, or generating a summary timesheet report.' This gives clear guidance on when to use this tool versus alternatives like time.entries.list for detailed entry review.

Agents often have multiple tools that could apply. Explicit usage 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 valuable behavioral context beyond annotations: it explains that archiving 'hides it from all queries' (impact on visibility) and that it's for 'permanently remove... without destroying the underlying data' (data preservation). Annotations already indicate destructiveHint=true and idempotentHint=true, but the description clarifies the specific soft-delete mechanism.

Agents need to know what a tool does to the 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 perfectly concise with two sentences that each earn their place: the first explains the action and effect, the second provides usage guidance. No wasted words, front-loaded with core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 operation with good annotations (destructiveHint=true, idempotentHint=true) and no output schema, the description provides excellent context about the soft-delete behavior and when to use it. The only minor gap is not explicitly mentioning what happens on repeated calls (though idempotentHint covers this).

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

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

With 100% schema description coverage, the schema already fully documents the single parameter (time_entry_id). The description doesn't add parameter-specific information beyond what's in the schema, so it meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the specific action ('soft-delete a time entry by setting its archived_at timestamp') and resource ('time entry'), distinguishing it from siblings like time.entries.create or time.entries.update. It explicitly explains what archiving means versus permanent deletion.

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

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

The description provides explicit guidance on when to use this tool ('when the freelancer wants to permanently remove an incorrectly logged or duplicate time entry from their records without destroying the underlying data'). It distinguishes this from hard deletion alternatives by explaining the soft-delete behavior.

Agents often have multiple tools that could apply. Explicit usage 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 this is a write operation (readOnlyHint: false) and non-destructive. The description adds useful context about billing implications ('tracked and later billed to the client'), but doesn't mention authentication requirements, rate limits, or error conditions. With annotations covering basic safety, this earns a baseline score.

Agents need to know what a tool does to the 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 perfectly concise with two sentences that each serve a distinct purpose: the first states what the tool does, the second provides usage context. There's no wasted language 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 creation tool with good annotations and full schema coverage, the description provides adequate context about purpose and usage. The main gap is the lack of output schema, but the description doesn't need to explain return values. It could benefit from mentioning prerequisites like project existence or user permissions.

Complex tools with many parameters or behaviors need more documentation. 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 itself. The description doesn't add any specific parameter details beyond what's already in the schema descriptions. This meets the baseline expectation when the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Log a time entry'), the target resource ('against a project'), and the purpose ('to record hours worked'). It distinguishes this tool from sibling time.entries.* tools by focusing on creation rather than retrieval, update, or aggregation.

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

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

The description provides clear context for when to use this tool ('when the freelancer reports time spent on a task, meeting, or deliverable') and the outcome ('so it can be tracked and later billed to the client'). However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying it retrieves 'a single time entry record' and mentions example details like description, duration, or billable status, giving context about what information is returned. However, it doesn't disclose additional behavioral traits like error conditions or response format.

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

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

The description is two sentences that are front-loaded with the core purpose and usage guidelines. Every word earns its place: the first sentence defines the tool, and the second provides explicit invocation context. There is no wasted text or redundancy.

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

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

Given the tool's simplicity (single parameter, 100% schema coverage, no output schema) and rich annotations, the description is mostly complete. It clearly states purpose, usage, and examples of returned details. However, without an output schema, it could benefit from more detail on the response structure (e.g., what fields are included beyond the examples).

Complex tools with many parameters or behaviors need more documentation. 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 the parameter 'time_entry_id' fully documented in the schema as a UUID. The description adds minimal semantic context by reinforcing it's a 'unique identifier' for retrieval, but doesn't provide additional details beyond what the schema already states. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Retrieve a single time entry record'), identifies the resource ('by its unique identifier'), and distinguishes it from siblings by specifying it's for viewing details of a specific logged time entry rather than listing, creating, updating, or aggregating entries. The mention of 'description, duration, or billable status' provides concrete examples of what details are available.

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

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

The description explicitly states when to use this tool: 'Use when the freelancer asks to view the details of a specific logged time entry.' This provides clear context for invocation and implicitly distinguishes it from siblings like time.entries.list (for multiple entries) or time.entries.aggregate (for summarized data).

Agents often have multiple tools that could apply. Explicit usage 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 this is a safe, read-only operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds valuable context by specifying the filtering capabilities (project, date range, billable status) and the tool's role in workflows like timesheet preparation and invoice checking. However, it doesn't mention pagination behavior (implied by limit/offset parameters) or rate limits.

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

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

The description is two sentences: the first states the purpose and filtering options, and the second provides usage guidelines. Every word earns its place with no redundancy or fluff, making it highly efficient and front-loaded with essential information.

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

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

For a read-only list tool with rich annotations (safety profile covered) and full schema coverage, the description is mostly complete. It adds workflow context and filtering scope. However, without an output schema, it doesn't describe the return format (e.g., array of time entry objects), leaving a minor gap in completeness.

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

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

Schema description coverage is 100%, so all parameters are well-documented in the schema itself. The description mentions filtering by 'project, date range, and billable status,' which aligns with parameters like project_id, start_date, end_date, and billable, but doesn't add meaningful semantic details beyond what the schema provides. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('List time entries') and resource ('time entries'), distinguishing it from siblings like 'time.entries.aggregate' (which summarizes) and 'time.entries.archive' (which deactivates). It specifies the filtering scope ('by project, date range, and billable status'), making the purpose explicit and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides three concrete use cases: 'reviewing logged hours for a project,' 'preparing a timesheet,' and 'checking what work has been recorded before generating an invoice.' This gives clear guidance on when to use this tool, though it doesn't explicitly mention when not to use it or name alternatives like 'time.entries.aggregate' for summaries.

Agents often have multiple tools that could apply. Explicit usage 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 valuable context beyond annotations: it clarifies this is for correcting existing entries, which implies it's a mutation tool (consistent with readOnlyHint=false). Annotations already cover idempotency (idempotentHint=true) and non-destructive nature (destructiveHint=false), but the description reinforces the correction purpose. No contradictions with annotations.

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

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

The description is two concise sentences with zero waste. The first sentence states the purpose and scope, while the second provides clear usage guidelines. Every word contributes to understanding the tool's function and when to use it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 is reasonably complete. It covers purpose, usage context, and behavioral intent. However, it doesn't mention potential side effects (e.g., impact on billing or reporting) or error conditions, which could be helpful given the lack of output schema.

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

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

The description mentions specific fields that can be updated (duration, description, date, billable flag), which aligns with the input schema parameters. However, with 100% schema description coverage, the schema already documents each parameter thoroughly. The description adds minimal semantic value beyond what's in the schema, meeting 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?

The description clearly states the action ('Update one or more fields'), the resource ('existing time entry record'), and provides specific examples of what can be updated (duration, description, date, billable flag). It distinguishes this from creation tools by specifying 'existing' and 'after it was originally saved,' differentiating it from sibling tools like time.entries.create.

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

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

The description explicitly states when to use this tool: 'when the freelancer needs to correct a logged entry's duration, description, date, or billable flag after it was originally saved.' This provides clear context for usage, including the actor (freelancer), timing (after original save), and purpose (correction). It implicitly distinguishes from creation tools by focusing on updates to existing records.

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