Server Quality Checklist

Tool Scores

• invoices.records.createA
  3.7/5.0
  Behavior3/5

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

  Annotations indicate this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false) that is not idempotent. The description adds value by specifying persistence to the 'FreelanceOS database' and mentioning the data structure (line items, tax, totals), but it does not disclose return values, validation behavior for calculations, or error conditions given the lack of an output schema.

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

  Conciseness5/5

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

  The description consists of two efficiently structured sentences with no waste. The first sentence front-loads the core action and scope, while the second provides usage context. Every word earns its place.

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

  Completeness3/5

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

  Given the tool's complexity (13 parameters including nested line items and financial calculations) and lack of output schema, the description is adequate but incomplete. It omits what the tool returns, whether the API validates mathematical consistency (subtotal + tax = total), and prerequisites like client existence verification.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is 3. The description mentions 'line items, tax, and totals,' which maps to key parameters, but does not add semantic clarifications beyond the schema (e.g., calculation validation rules, relationships between amount/quantity/rate fields).

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

  Purpose4/5

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

  The description clearly states the tool 'Create[s] and persist[s] a new invoice with line items, tax, and totals in the FreelanceOS database,' providing specific verbs and resources. However, it does not explicitly differentiate from sibling tool 'invoices.records.update' beyond implying 'new' invoice creation.

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

  Usage Guidelines4/5

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

  The second sentence provides clear context for when to use the tool: 'Use when the freelancer wants to generate and save a billable invoice for a completed or ongoing project.' While this establishes the triggering scenario well, it lacks explicit exclusions or named alternatives (e.g., when to use update vs create).

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

• time.entries.listA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and repeatability. The description adds business context (timesheet/invoice workflows) but does not disclose pagination behavior implications, rate limits, or return format details—gaps that matter given the lack of output schema.

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

  Conciseness5/5

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

  Two well-structured sentences with zero waste. Front-loaded with the action verb 'List,' followed by filtering capabilities, then usage scenarios. Every sentence earns its place.

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

  Completeness3/5

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

  With 8 parameters and no output schema, the description should explicitly state what the tool returns (e.g., 'returns a paginated list of time entry records'). While 'List time entries' implies this, the absence of return value documentation and lack of sibling differentiation leaves gaps for a tool of this complexity.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing a baseline of 3. The description mentions project, date range, and billable filters, grouping start_date/end_date conceptually, but does not add syntax details, format examples, or explain the sorting/pagination parameters (sort_by, limit, offset) beyond what the schema provides.

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

  Purpose4/5

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

  Clear verb (List) + resource (time entries) + specific filterable dimensions (project, date range, billable status). However, it does not explicitly distinguish from sibling tool 'time.entries.get' (single record retrieval) or 'time.entries.aggregate' (summarized data), which could cause selection ambiguity.

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

  Usage Guidelines4/5

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

  Provides concrete usage scenarios: 'reviewing logged hours,' 'preparing a timesheet,' and 'checking work before generating an invoice.' Lacks explicit negative constraints (when NOT to use) or named alternatives for single-record lookup or aggregation.

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

• proposals.records.createA
  3.8/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=false and destructiveHint=false; the description confirms write behavior with 'persist it to the database.' However, it does not clarify the idempotentHint=false (whether duplicates are created on retry) or what success/failure looks like. Complements but doesn't significantly extend annotation coverage.

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

  Conciseness5/5

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

  Two well-structured sentences with zero redundancy: first defines the action and captured data, second specifies the trigger condition. Every word earns its place; appropriately front-loaded with the core verb.

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

  Completeness4/5

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

  Given the 7 parameters with full schema documentation and behavioral annotations, the description provides sufficient context for invocation. Minor gap: does not describe return values (presumably the created record ID), which would be helpful since no output schema exists.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing baseline 3. The description maps conceptual terms (deliverables, pricing, expiry) to schema fields (content, amount/currency, valid_until) but does not add syntactic details or validation rules beyond the comprehensive schema.

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

  Purpose4/5

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

  The description clearly states the tool 'stores a new proposal' with specific details (title, deliverables, pricing, expiry), distinguishing it from sibling operations like update or accept. The verb 'store' slightly less precise than 'create', but 'new proposal' effectively signals this is for initial creation.

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

  Usage Guidelines4/5

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

  Explicitly states when to use: 'when the freelancer has drafted proposal content and wants to persist it to the database.' This contextualizes the tool for the agent. Could be improved by explicitly contrasting with proposals.records.update for existing records.

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

• followups.messages.listA
  3.9/5.0
  Behavior3/5

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

  Annotations declare read-only, non-destructive, idempotent safety properties. The description adds value by disclosing 'pagination support' and distinguishing between 'drafts' (unsent) and 'sent communications' behavioral states. Does not mention rate limits, auth requirements, or response structure, but meets baseline expectations given annotation coverage.

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

  Conciseness5/5

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

  Two sentences with zero waste: first states purpose and capabilities, second provides usage triggers. Information is front-loaded (action before context) and appropriately sized for an 8-parameter list operation.

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

  Completeness4/5

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

  Given the rich input schema (100% coverage), clear annotations, and lack of output schema, the description provides sufficient context by mentioning pagination and filtering capabilities. It appropriately focuses on input semantics and usage triggers rather than return values, which is acceptable for a standard list operation.

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

  Parameters4/5

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

  Despite 100% schema description coverage, the description adds semantic mapping by linking 'client or project' to the ID parameters, 'pagination' to limit/offset, and 'drafts' vs 'sent communications' to the boolean 'sent' filter. This contextualizes raw parameters into business concepts.

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

  Purpose4/5

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

  The description clearly states the tool 'List[s] and filter[s] follow-up records' with specific scope (client/project) and capability (pagination). However, it does not explicitly distinguish from sibling tool 'followups.messages.get' (single record retrieval vs. list), though the verb 'List' provides implicit differentiation.

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

  Usage Guidelines4/5

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

  Provides explicit positive guidance with three concrete scenarios: 'review follow-up history', 'check outstanding drafts', and 'audit all sent communications'. Lacks explicit negative guidance (when NOT to use) or named alternatives, but the use-cases are specific enough to guide selection.

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

• scope.changes.listA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds value by noting 'optional filtering' and 'configurable sort order' capabilities, but does not disclose pagination behavior, error handling (e.g., invalid project_id), or response structure given the lack of output schema.

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

  Conciseness5/5

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

  Two tightly constructed sentences with zero waste. The first sentence front-loads core functionality, while the second provides concrete usage scenarios. Every word earns its place.

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

  Completeness3/5

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

  Despite comprehensive input schema coverage, the absence of an output schema creates a gap the description fails to fill. It does not describe the return format, pagination envelope structure, or what constitutes a 'scope change request' object, which is necessary information given the lack of structured output documentation.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is appropriately met. The description reinforces the key optional parameters by explicitly mentioning 'filtering by classification' and 'configurable sort order,' helping prioritize which parameters drive the query behavior, though it adds no syntactic details beyond the schema.

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

  Purpose5/5

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

  The description clearly states the specific verb (List), resource (scope change requests), and scope (logged against a project). It effectively distinguishes from siblings like scope.changes.log (which creates entries) and scope.definition.* (which manages baseline scope rather than change requests).

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

  Usage Guidelines4/5

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

  Provides explicit 'Use when' scenarios covering three distinct business contexts: scope creep review, change-order preparation, and billing audits. However, it lacks explicit 'when-not-to-use' guidance or mention of alternatives like scope.changes.log for creating new change requests.

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

• followups.messages.createA
  4/5.0
  Behavior3/5

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

  Annotations indicate this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false) and not idempotent (idempotentHint: false). The description adds valuable context that storage can occur 'before or after sending,' clarifying this tracks both drafts and sent message records. However, it omits what the tool returns on success, whether duplicates are created on retry (though annotations cover idempotency), or any side effects.

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

  Conciseness5/5

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

  Two sentences with zero waste: first defines the action, second defines the usage context. The description is front-loaded with the core verb and resource, making it immediately scannable. Every word earns its place.

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

  Completeness4/5

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

  Given this is a creation tool with 5 well-documented parameters (100% schema coverage) and no output schema, the description adequately covers the essential behavioral context (draft storage, tracking purpose, timing relative to sending). It could be improved by describing the return value or distinguishing more explicitly from followups.messages.update, but it is sufficient for correct invocation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents all 5 parameters including the enum values for 'type' and UUID patterns. The description implies the content and subject through 'drafted follow-up message' and client_id through 'to the client,' but does not add syntax details, validation rules, or parameter relationships beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states the specific action ('Store a drafted follow-up message'), the resource type (drafted follow-up), and the system (FreelanceOS database). It clearly distinguishes from sibling tools like followups.messages.update or followups.sent.mark by emphasizing this is for initial drafting/saving, not modification or marking sent status.

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

  Usage Guidelines4/5

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

  The description provides clear context with 'Use when the freelancer has composed a follow-up and wants to save it for tracking purposes before or after sending it to the client.' This establishes the workflow timing and purpose. However, it does not explicitly name alternative tools (like followups.messages.update for editing existing drafts) or explicitly state 'do not use this to send messages'.

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

• followups.messages.updateA
  4/5.0
  Behavior3/5

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

  Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds valuable lifecycle context ('drafted', 'before sending') but doesn't disclose additional behavioral traits like error handling for invalid UUIDs or partial update semantics (are omitted fields preserved?).

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

  Conciseness5/5

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

  Two well-structured sentences with zero waste. First sentence defines the operation; second provides the specific usage context. Information is front-loaded 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.

  Completeness4/5

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

  Given the 100% schema coverage, clear annotations, and absence of an output schema, the description provides sufficient context. It explains the business purpose (revising before sending) and parameter scope, though it could briefly note the idempotent nature or success behavior.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is 3. The description adds semantic mapping by listing the specific fields that can be revised ('subject, body, type, or project association'), reinforcing the schema's parameter purposes without duplicating technical constraints.

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

  Purpose5/5

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

  The description clearly states the specific action (update content or metadata) and resource (existing follow-up record). It effectively distinguishes from siblings like 'followups.messages.create' by emphasizing 'revise a drafted follow-up' and from 'followups.sent.mark' by specifying 'before sending it to the client.'

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

  Usage Guidelines4/5

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

  Provides clear when-to-use context: 'Use when the freelancer wants to revise a drafted follow-up... before sending it to the client.' This implies the pre-send lifecycle state, though it could be more explicit about alternatives (e.g., 'use create for new follow-ups').

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

• invoices.records.getA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'full details' (suggesting complete object retrieval) and reinforces the UUID lookup pattern, but does not disclose error handling (e.g., archived invoice behavior), rate limits, or cache semantics that would be valuable beyond the structured annotations.

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

  Conciseness5/5

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

  Two well-structured sentences with zero redundancy: first defines the operation, second defines the usage trigger. Front-loaded with the action verb and appropriately sized for the tool's simplicity.

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

  Completeness4/5

  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, simple getter) and rich supporting metadata (100% schema coverage, comprehensive annotations), the description is sufficient. Minor gap: lacks description of return value structure, though 'full details' provides some hint of the output shape.

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

  Parameters3/5

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

  With 100% schema description coverage, the parameter invoice_id is fully documented in the schema itself ('UUID of the invoice to retrieve...'). The description mentions 'by its UUID' which aligns with the schema, but adds no additional semantic context (formats, validation edge cases) beyond what the schema already provides. Baseline 3 is appropriate for high-coverage schemas.

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

  Purpose5/5

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

  The description provides a specific verb ('Retrieve'), resource ('invoice'), and scope constraint ('single invoice by its UUID'). It clearly distinguishes from sibling tools like invoices.records.list (implied by 'single') and invoices.records.update (implied by 'Retrieve' vs mutative operations).

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

  Usage Guidelines4/5

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

  Explicitly states the trigger condition ('Use when the freelancer asks to view, review, or share'), providing clear context for when to invoke. However, it does not explicitly name alternative tools (e.g., 'use invoices.records.list for searching multiple invoices'), stopping short of a perfect score.

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

• invoices.records.updateA
  4/5.0
  Behavior3/5

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

  Annotations already declare idempotentHint=true and destructiveHint=false. Description adds value by noting partial updates are possible ('one or more fields'), but does not disclose behavioral nuances like the line_items array being a full replacement (though this is documented in schema) or specific error conditions. Does not contradict annotations.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence establishes capability; second provides usage context. Perfectly front-loaded with no redundant or filler text.

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

  Completeness4/5

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

  With 11 parameters and 100% schema coverage, the description appropriately focuses on high-level capabilities and use cases rather than enumerating all fields. Adequately covers the complex line_items parameter through the 'corrects line items' example. Minor gap: does not mention idempotency explicitly (relying on annotation) or notes field.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing baseline 3. Description adds conceptual grouping ('financial totals' covering subtotal/tax/total) and maps usage scenarios to parameters (due date, line items), but does not add syntax, format, or dependency details beyond the schema.

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

  Purpose5/5

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

  Description states specific action ('Update one or more fields') on specific resource ('existing invoice'), explicitly mentioning updatable categories ('status or financial totals'). Clearly distinguishes from sibling tools create/get/list through the 'update' verb and 'existing invoice' qualifier.

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

  Usage Guidelines4/5

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

  Provides concrete usage scenarios in second sentence: 'marks an invoice as sent, records a payment, corrects line items, or changes the due date.' This gives the agent clear signals for when to invoke. Lacks explicit 'when not to use' or named alternatives, but the scenarios provide strong contextual guidance.

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

• projects.records.createA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, establishing this as a safe write operation. The description adds 'persist it to the FreelanceOS database' which confirms durability, but does not elaborate on idempotency (covered by annotations), error conditions, or side effects beyond what structured fields provide.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence defines the action and technical effect; second sentence provides usage context. Efficiently front-loaded with the core operation.

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

  Completeness4/5

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

  Appropriate for a creation tool with good annotations and complete input schema. No output schema exists, so description cannot document return values (likely the created project ID). Missing only minor behavioral details like validation errors or duplicate handling.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing baseline 3. The description conceptually maps parameters to their purpose ('track budget, timeline'), reinforcing client_id's necessity via 'linked to an existing client', but does not add syntax details or format guidance beyond the comprehensive schema.

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

  Purpose5/5

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

  Description provides specific verb ('Create'), resource ('project'), and scope ('linked to an existing client', 'persist to FreelanceOS database'). It distinguishes from sibling tools like clients.records.create by explicitly mentioning the client relationship and project-specific attributes (budget, timeline).

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

  Usage Guidelines4/5

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

  Explicitly states when to use ('when a freelancer is starting new work for a client and needs to track budget, timeline, and status'). Provides clear contextual trigger. Lacks explicit 'when not to use' or named alternatives (e.g., vs. update), but the condition is specific enough to prevent misuse.

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

• proposals.records.listA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds scope context about filtering capabilities and pagination support, but does not disclose additional behavioral traits like rate limits, default sort behavior, or maximum result sets beyond what the schema shows.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence front-loads the core functionality with specific filtering dimensions. Second sentence provides usage scenarios. Every word earns its place.

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

  Completeness4/5

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

  For a 7-parameter list operation with 100% schema coverage and no output schema, the description is appropriately complete. It covers the filtering taxonomy and pagination behavior sufficiently. Could improve by noting that all filters are optional (0 required params) or mentioning default sort order, but this is minor given schema clarity.

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

  Parameters3/5

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

  Schema has 100% description coverage, establishing baseline 3. The description adds conceptual grouping by referencing 'filtered by project, client, or status' (three filter params) and 'sorting and pagination' (sort_by, sort_dir, limit, offset), which helps the agent map use cases to parameters, but does not add syntactic or semantic details beyond the schema.

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

  Purpose5/5

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

  The description clearly states the core action ('List proposals') along with specific capabilities (filtering by project/client/status, sorting, pagination). It effectively distinguishes from siblings like proposals.records.get (single record) and proposals.records.create/update/accept (mutations) through the list-focused language and filter parameters.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance with three concrete scenarios: 'proposal history,' 'audit outstanding proposals,' and 'check status of proposals sent to a client.' Lacks explicit 'when not to use' or direct sibling comparisons (e.g., vs. get for single records), but the positive guidance is strong and specific.

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

• scope.definition.createA
  4/5.0
  Behavior3/5

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

  Annotations indicate this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false), which the description confirms with 'persist'. However, given idempotentHint: false, the description should warn that multiple invocations create duplicate scope records, but it omits this critical behavioral detail.

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

  Conciseness5/5

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

  Two sentences totaling 38 words. The first sentence establishes purpose and scope components; the second provides usage timing. Every word earns its place with zero redundancy or filler content.

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

  Completeness4/5

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

  Given 100% schema coverage and present annotations, the description appropriately focuses on workflow integration rather than parameter details. It adequately covers the creation context, though it could improve by mentioning error behavior when a scope already exists or the non-idempotent nature of the operation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema adequately documents all parameters. The description lists three of five parameters (deliverables, boundaries, exclusions) but does not add semantic meaning beyond what the schema already provides, meeting the baseline for high-coverage schemas.

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

  Purpose5/5

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

  The description uses specific verbs ('Define and persist') and identifies the resource ('project scope') along with key components (deliverables, boundaries, exclusions). It clearly distinguishes this creation tool from siblings like scope.definition.update and scope.definition.get by emphasizing the initial establishment of scope.

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

  Usage Guidelines4/5

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

  Provides explicit temporal context for usage ('when starting a new project or immediately after a proposal is accepted'). This gives clear guidance on when to invoke the tool versus alternatives, though it does not explicitly name scope.definition.update as the alternative for modifying existing scopes.

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

• time.entries.aggregateA
  4/5.0
  Behavior3/5

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

  Annotations already establish readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable business context about billable hours and date range filtering, but doesn't clarify whether archived entries are included or describe the return structure/pagination.

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

  Conciseness5/5

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

  Two perfectly constructed sentences with zero waste: first establishes the calculation scope and resource, second provides specific business contexts for invocation. Information is front-loaded and efficiently structured.

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

  Completeness4/5

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

  Given the 100% schema coverage and strong annotations, the description adequately covers inputs and use cases. It mentions calculating 'minutes and hours' which partially compensates for the missing output schema. Minor deduction for not specifying the exact return structure (object vs. scalar) or whether the aggregation includes archived entries.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all four parameters fully documented (project_id, date range fields, billable_only). The description references 'optional date range' and 'billable hours' adding semantic context, but doesn't add technical details (format syntax, constraint logic) beyond what the schema provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses specific verbs ('Calculate') and clearly identifies the resource ('total minutes and hours logged against a project') and scope ('over an optional date range'). It effectively distinguishes this from CRUD sibling tools (time.entries.create, list, etc.) by focusing on aggregation/summation rather than entry management.

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

  Usage Guidelines4/5

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

  Provides explicit positive guidance with three specific scenarios ('preparing an invoice', 'verifying billable hours', 'generating a summary timesheet report'). However, it lacks explicit negative guidance or contrast with siblings like time.entries.list (which returns individual entries vs. aggregates).

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

• clients.records.listA
  4.2/5.0
  Behavior4/5

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

  Annotations already establish read-only, non-destructive, idempotent safety. The description adds crucial behavioral context not in annotations: the active-only filter ('non-archived') which governs data scope. It also implies pagination behavior through the capability list, adding useful context beyond the structured hints.

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

  Conciseness5/5

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

  Two sentences totaling one line. The first sentence front-loads the core action and scope; the second provides usage context. Every word earns its place—no redundancy with the title (which is null) or annotations.

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

  Completeness4/5

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

  Given the rich annotations (4 hints provided), 100% input schema coverage, and absence of an output schema, the description successfully covers the essential behavioral contract (active-only filtering) and usage patterns. It adequately compensates for missing output schema by clarifying the list nature of the operation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema carries the full burden of parameter documentation. The description provides conceptual grouping ('name search', 'sorting', 'pagination') mapping to the five parameters, but does not add semantic meaning beyond what the schema already provides. Baseline 3 is appropriate given the schema richness.

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

  Purpose5/5

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

  The description opens with a specific verb ('List'), clear resource ('active (non-archived) clients'), and complete capability set ('optional name search, sorting, and pagination'). The 'non-archived' qualifier effectively distinguishes this from clients.records.archive, while 'List all' implies bulk retrieval distinguishing it from clients.records.get.

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

  Usage Guidelines4/5

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

  The second sentence provides explicit when-to-use guidance with three specific freelancer scenarios ('overview of their client roster', 'look up a client by name', 'present a list... to choose from'). However, it does not explicitly name alternative tools like clients.records.get for single-record retrieval or indicate when to use archive-related tools.

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

• clients.records.updateA
  4.2/5.0
  Behavior4/5

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

  Annotations establish write-access (readOnlyHint: false) and safety (destructiveHint: false, idempotentHint: true). The description adds valuable behavioral context beyond these hints by explicitly stating the partial-update semantics ('all others remain untouched'), clarifying that this is not a full replacement operation.

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

  Conciseness5/5

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

  Two sentences total with zero redundancy. Front-loaded with the core operation, followed immediately by use-case context and behavioral constraints. Every clause serves a distinct purpose: defining the operation, specifying the actor/intent, and explaining side effects.

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

  Completeness4/5

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

  Given the 8-parameter schema with complete coverage and helpful annotations, the description provides sufficient context for tool selection. It appropriately covers the partial-update behavior essential for this tool type. Minor gap: no mention of return values or error states (e.g., invalid client_id), though this is partially mitigated by the idempotentHint annotation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema itself fully documents parameter semantics (types, formats, nullability). The description references specific fields (contact details, billing rate) in examples, but this provides marginal additive value over the comprehensive schema. Baseline 3 is appropriate for high-coverage schemas.

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

  Purpose5/5

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

  The description opens with a precise action ('Update one or more fields') and resource ('existing client record'), and uses specific examples (contact details, billing rate, notes) that map directly to schema parameters. It clearly distinguishes from siblings like 'create' by emphasizing 'existing' and partial field updates.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance ('Use this tool when a freelancer wants to...') with concrete scenarios. Explains critical behavioral semantics ('only the fields you provide will be changed') that guide the agent toward PATCH-like usage. Lacks explicit naming of sibling alternatives (e.g., 'use create for new clients'), though this is implicitly clear.

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

• followups.messages.getA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare read-only, non-destructive, and idempotent traits. The description adds valuable behavioral context about the returned payload ('including its content, type, and sent status'), disclosing what specific data fields the agent can expect to receive beyond what the schema structure implies.

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

  Conciseness5/5

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

  Two tightly constructed sentences with zero redundancy. The first states the action, the second states the trigger condition and return value details. Information is front-loaded and every clause earns its place.

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

  Completeness4/5

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

  For a simple single-parameter retrieval tool, the description is complete. It compensates for the missing output schema by explicitly listing the key returned fields (content, type, sent status). It could reach 5 by briefly noting error behavior (e.g., invalid UUID) or pagination (none needed here).

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

  Parameters3/5

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

  Schema description coverage is 100% with the followup_id parameter fully documented ('Unique UUID identifier...'). The description references 'unique ID' aligning with the schema, but adds no additional syntax constraints or format details beyond the excellent schema coverage, meeting the baseline.

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

  Purpose5/5

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

  The description uses a specific verb ('Retrieve') with a clear resource ('single follow-up record') and scope ('by its unique ID'). It implicitly distinguishes from siblings like followups.messages.list (plural retrieval) and followups.messages.create (mutation) through the singular 'single' and verb choice.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use context ('when the freelancer asks to view the full details of a specific saved follow-up'). It implies the singular nature distinguishing it from list operations, though it could be strengthened by explicitly naming the list alternative for bulk retrieval.

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

• followups.sent.markA
  4.2/5.0
  Behavior4/5

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

  Annotations cover idempotency and safety (idempotentHint=true, destructiveHint=false). The description adds valuable behavioral context beyond annotations: the state machine transition ('draft to sent'), automatic timestamp recording ('current timestamp'), and the critical context that this is for external sending ('outside of FreelanceOS').

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

  Conciseness5/5

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

  Two sentences with zero waste: first states the technical action, second states the business trigger. Every word earns its place. Front-loaded with the core verb ('Record').

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

  Completeness4/5

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

  Given the simple single-parameter input and clear annotations, the description adequately covers the business logic. For a simple state-transition tool without output schema, it sufficiently explains the operation. Minor gap: doesn't describe return value or error states (e.g., invalid UUID), though this is less critical for an idempotent update operation.

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

  Parameters3/5

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

  Schema description coverage is 100% ('Unique UUID of the follow-up record...'), so the schema fully documents the parameter. The description focuses on behavioral semantics rather than repeating parameter details, which is appropriate given the high schema coverage.

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

  Purpose5/5

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

  The description specifies the exact action ('Record the current timestamp', 'transitioning it from draft to sent status') and resource (follow-up). It clearly distinguishes from sibling message-management tools (followups.messages.*) by focusing on the sent-status state transition rather than content creation.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance: 'Use when the freelancer confirms they have actually sent the follow-up message to the client outside of FreelanceOS.' This external/outside-system distinction is crucial for tool selection. Lacks explicit 'when not to use' or named alternatives (e.g., don't use if sending through FreelanceOS itself).

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

• invoices.records.listA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: 'paginated' (indicating limit/offset usage) and 'filtered' (indicating parameter-based filtering). 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.

  Conciseness5/5

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

  Two well-structured sentences with zero waste. First sentence establishes purpose; second provides usage context. Information is front-loaded and every word earns its place.

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

  Completeness4/5

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

  Appropriately complete for a list tool with 9 optional parameters and strong annotation coverage. Description establishes freelancer context and pagination behavior. Absence of output schema is noted, though description doesn't attempt to describe return structure.

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

  Parameters3/5

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

  Schema description coverage is 100%, establishing baseline 3. The description adds semantic mapping of business concepts ('outstanding', 'overdue', 'revenue summary') to filtering capabilities but does not need to compensate for schema gaps.

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

  Purpose5/5

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

  The description uses specific verb 'Return' with clear resource 'invoices' and scope 'for the authenticated freelancer'. It distinguishes from siblings (create/update/get) by emphasizing 'paginated, filtered list' and mentioning specific use cases like revenue summaries.

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

  Usage Guidelines4/5

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

  Provides clear when-to-use guidance ('Use when the freelancer asks about...') mapping business needs (outstanding, paid, overdue, draft, revenue summary) to the tool. Lacks explicit mention of when to use sibling 'invoices.records.get' for single records instead of listing.

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

• projects.records.getA
  4.2/5.0
  Behavior4/5

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

  While annotations declare read-only/idempotent status, the description adds valuable behavioral context by disclosing that the operation joins/returns 'associated client name and contact information' alongside project data, indicating the breadth of the returned payload.

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

  Conciseness5/5

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

  Two well-structured sentences: first states functionality and return data, second states usage context. No redundancy or wasted words; information density is high.

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

  Completeness4/5

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

  For a simple read operation with good annotations and no output schema, the description adequately covers the return value contents (client info, status, budget, timeline) and usage context. Slight gap in not mentioning error cases (e.g., project not found).

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

  Parameters3/5

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

  With 100% schema description coverage for the single 'project_id' parameter, the schema fully documents inputs. The description mentions 'single project' which aligns with the parameter requirement but does not add semantic details beyond the schema's UUID specification.

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

  Purpose5/5

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

  The description uses specific verb 'Retrieve' with resource 'project' and scope 'single project', clearly distinguishing from the sibling 'projects.records.list'. It also clarifies this includes associated client data, distinguishing it from 'clients.records.get'.

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

  Usage Guidelines4/5

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

  Explicitly states when to use ('when a freelancer asks about a specific project's status, budget, or timeline'), providing clear context. However, it does not explicitly name the alternative 'projects.records.list' for multi-project queries, which would complete the guidance.

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

• projects.records.updateA
  4.2/5.0
  Behavior4/5

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

  Annotations cover the safety profile (readOnlyHint: false, destructiveHint: false, idempotentHint: true). The description adds valuable domain context beyond annotations: it clarifies partial update semantics ('one or more fields'), maps technical fields to business workflows (marking projects paused/completed), and specifies the user context (freelancer). It does not mention error handling (e.g., invalid project_id) or validation constraints (e.g., date ordering), which prevents a 5.

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

  Conciseness5/5

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

  Two well-structured sentences with zero redundancy. The first front-loads the core action and scope; the second provides usage scenarios. Every word earns its place—specific fields are enumerated, and the freelancer context is economically established without verbose exposition.

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

  Completeness4/5

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

  Given rich schema coverage (100%) and comprehensive annotations (idempotentHint, etc.), the description provides sufficient context for tool selection. It covers the update semantics, required identifier (project_id), and business use cases. A 5 would require addressing error scenarios (e.g., 'returns error if project not found') or validation logic (e.g., end_date must follow start_date), but the current level is adequate for invocation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents all 8 parameters including formats (UUID, ISO dates) and constraints. The description lists corresponding fields ('name, description, budget, dates') but adds minimal semantic detail beyond the schema's comprehensive descriptions. Baseline 3 is appropriate when the schema carries the descriptive burden.

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

  Purpose5/5

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

  The description explicitly states the action ('Update one or more fields'), the resource ('existing project record'), and lists specific updatable fields (name, description, budget, dates, lifecycle status). It clearly distinguishes this from sibling tools like projects.records.create or archive by emphasizing 'existing' records and partial field updates.

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

  Usage Guidelines4/5

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

  The second sentence provides explicit when-to-use guidance ('Use this tool when a freelancer wants to edit project details...'), covering key scenarios like budget revision, timeline adjustment, and status changes. It lacks explicit when-not-to-use guidance or named alternatives (e.g., 'do not use for creating new projects'), but the 'existing record' qualifier provides implicit differentiation from the create sibling.

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

• proposals.records.acceptA
  4.2/5.0
  Behavior4/5

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

  Annotations declare idempotentHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond annotations: explicitly states the operation is atomic, discloses side effects (seeding linked project's scope_definitions from deliverables), and notes timestamp recording. Does not mention idempotency explicitly but annotations cover this.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence front-loads the core action and critical side effects (atomic operation, scope seeding). Second sentence provides usage context. Every word earns its place.

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

  Completeness4/5

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

  Given the single parameter and absence of an output schema, the description adequately covers the business logic complexity (workflow state change with cascading side effects). It explains what happens (marking accepted, seeding scope) sufficiently for agent selection, though explicit error conditions or return value details could improve it further.

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

  Parameters3/5

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

  Schema description coverage is 100% (proposal_id fully documented with format and semantics). The description does not add additional parameter context beyond what the schema provides, earning the baseline score for high-coverage schemas.

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

  Purpose5/5

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

  The description uses specific verbs (mark, record, seed) and clearly identifies the resource (proposal) and scope (atomic operation including side effects on linked project scope_definitions). It effectively distinguishes from sibling tools like proposals.records.update by emphasizing the specific acceptance workflow and automatic scope seeding behavior.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance ('Use when the freelancer confirms that a client has accepted the proposal and work is ready to begin'). Lacks explicit when-not-to-use guidance or named alternatives (e.g., distinguishing from general status updates via proposals.records.update), preventing a perfect score.

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

• scope.definition.getA
  4.2/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond these annotations by specifying it retrieves the 'current active' definition (distinguishing from historical changes) and detailing what content is included (deliverables, boundaries, assumptions, exclusions). 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.

  Conciseness5/5

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

  Two well-structured sentences: first defines the action and content, second provides usage context. Zero redundancy. Information density is high with no filler words. Front-loaded with the core action 'Retrieve'.

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

  Completeness4/5

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

  Given the tool has 100% schema coverage, clear annotations, and only one parameter, the description adequately covers the tool's purpose and usage. It compensates for the lack of output schema by listing what fields the scope definition includes. Minor gap: doesn't specify behavior when no scope exists for the project.

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

  Parameters3/5

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

  With 100% schema description coverage ('UUID of the project whose scope definition should be retrieved'), the schema carries the full semantic load. The description references 'for a project' which aligns with the parameter but does not add syntax, format, or validation details beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('Retrieve') with clear resource ('current active scope definition') and enumerates specific content components (deliverables, boundaries, assumptions, exclusions). It clearly distinguishes from sibling mutation tools like scope.definition.create/update by emphasizing 'Retrieve' and 'current active'.

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

  Usage Guidelines4/5

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

  Provides explicit positive guidance ('Use when the freelancer wants to review exactly what was agreed... before starting work or answering a scope question'). However, it lacks explicit negative guidance or mentions of alternatives (e.g., don't use this to modify scope; use scope.definition.update instead).

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

• scope.definition.updateA
  4.2/5.0
  Behavior4/5

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

  Annotations declare idempotentHint=true and destructiveHint=false, but the description adds valuable business context: the update requires mutual agreement and modifies the 'persisted record.' It clarifies this is a formal contractual update, not a draft or tentative change, which complements the technical safety annotations well.

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

  Conciseness5/5

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

  The description consists of exactly two high-value sentences with zero redundancy. It is front-loaded with the action verb, immediately followed by scope and conditional usage guidance. Every word earns its place.

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

  Completeness4/5

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

  Given the 100% schema coverage and comprehensive annotations, the description adequately covers the business logic (mutual agreement requirement). It could be improved by mentioning whether this triggers side effects like notifications or versioning entries, but it is sufficient for a standard update operation.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents all five parameters (project_id, deliverables, boundaries, assumptions, exclusions). The description confirms partial updates are supported ('one or more fields') but does not add semantic details beyond what the schema already provides, warranting the baseline score.

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

  Purpose5/5

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

  The description specifies the exact action ('Update one or more fields'), the target resource ('active scope definition'), and the domain ('for a project'). It distinguishes from siblings like scope.definition.create (which creates new definitions) and scope.definition.get (which retrieves) by emphasizing modification of the active persisted record.

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

  Usage Guidelines4/5

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

  The second sentence provides explicit contextual guidance: 'Use when the client and freelancer have mutually agreed to change the scope.' This establishes the prerequisite business condition. However, it does not explicitly mention alternatives like scope.changes.log for tracking history or scope.definition.create for initial creation.

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

• time.entries.createA
  4.2/5.0
  Behavior4/5

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

  Annotations indicate this is a non-destructive write operation (readOnlyHint=false, destructiveHint=false). The description adds valuable business context beyond these annotations by noting entries can be 'later billed to the client,' clarifying the data lifecycle. It appropriately does not contradict the idempotentHint=false (implied by 'log' suggesting record creation).

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

  Conciseness5/5

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

  Two well-structured sentences with zero waste: the first defines the action, the second provides usage context. Information is front-loaded with the core purpose ('Log a time entry'), making it immediately scannable.

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

  Completeness4/5

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

  Given the rich input schema (5 well-documented parameters), appropriate annotations, and absence of an output schema, the description provides sufficient context by explaining the business workflow (tracking for billing). It appropriately focuses on intent rather than replicating schema technicalities.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is appropriately 3. The description implicitly references parameters (project, hours worked, deliverables) but does not add syntax details, format constraints, or semantic relationships beyond what the comprehensive schema already provides.

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

  Purpose5/5

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

  The description explicitly states the tool 'Log[s] a time entry against a project to record hours worked,' providing a specific verb (log), resource (time entry), and scope (against a project). This clearly distinguishes it from sibling operations like aggregate, archive, list, or update.

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

  Usage Guidelines4/5

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

  The description provides clear contextual guidance: 'Use when the freelancer reports time spent on a task, meeting, or deliverable so it can be tracked and later billed to the client.' While it effectively establishes the 'when' (freelancer reporting) and business purpose (billing), it does not explicitly name sibling alternatives or contraindications.

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

• time.entries.getA
  4.2/5.0
  Behavior4/5

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

  Annotations cover safety profile (read-only, idempotent), while the description adds valuable behavioral context about what data is returned ('description, duration, or billable status'), compensating for the missing output schema.

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

  Conciseness5/5

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

  Two well-structured sentences with zero redundancy: first states the operation, second states the usage trigger. Every word serves a purpose.

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

  Completeness4/5

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

  For a simple single-parameter read operation, the description is complete. It compensates for the lack of output schema by listing representative fields returned, though explicit mention of error cases (e.g., 'entry not found') would elevate this to a 5.

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

  Parameters3/5

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

  With 100% schema description coverage, the schema fully documents the time_entry_id parameter. The description references 'unique identifier' but adds no syntax, format, or semantic details beyond the schema's UUID pattern and description.

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

  Purpose5/5

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

  The description uses specific verb 'Retrieve' with clear resource scope 'a single time entry record by its unique identifier', effectively distinguishing it from sibling tools like time.entries.list or time.entries.aggregate which handle multiple records.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use context ('when the freelancer asks to view the details of a specific logged time entry'), establishing the requirement for a specific ID. Lacks explicit contrast with time.entries.list for when the ID is unknown.

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

• time.entries.updateA
  4.2/5.0
  Behavior4/5

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

  Annotations declare idempotentHint=true and non-destructive behavior. The description adds valuable behavioral context beyond annotations by specifying partial update capability ('one or more fields') and enumerating which specific fields are mutable. It does not mention error behavior (e.g., invalid UUID), but covers the essential operational semantics.

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

  Conciseness5/5

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

  Two tightly constructed sentences with zero redundancy. First sentence defines the operation; second sentence defines the usage trigger. Every word serves a purpose—no filler or obvious tautology.

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

  Completeness4/5

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

  Given the straightforward partial-update semantics, 100% schema coverage, and complete annotation set (including idempotency), the description provides sufficient context for safe invocation. No output schema exists, but the description appropriately focuses on input semantics and intent rather than return values.

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

  Parameters3/5

  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 five parameters (time_entry_id, description, duration_minutes, entry_date, billable). The description provides conceptual grouping of these fields but does not add syntax, format constraints, or examples beyond what the schema already specifies. Baseline 3 is appropriate when schema carries the full documentation burden.

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

  Purpose5/5

  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) and target resource (existing time entry record). It implicitly distinguishes from sibling 'time.entries.create' by emphasizing 'existing' and 'after it was originally saved,' and from 'time.entries.archive' by focusing on correction rather than removal.

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

  Usage Guidelines4/5

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

  Provides explicit 'Use when' guidance specifying the correction scenario (duration, description, date, or billable flag) and timing (after originally saved). Deducting one point because it does not explicitly name 'time.entries.create' as the alternative for new entries, though this is strongly implied.

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

• projects.records.archiveA
  4.3/5.0
  Behavior4/5

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

  Adds crucial context beyond annotations: clarifies that destructiveHint=true refers to state-changing archival (soft-delete), not data loss; explains the mechanism ('setting its archived_at timestamp'); and discloses side effects ('hiding it from all active project lists'). Does not mention rate limits or auth requirements.

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

  Conciseness5/5

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

  Two sentences, zero waste. First sentence front-loads the action and mechanism; second sentence provides usage context. Every word earns its place with no redundant fluff or repetition of structured metadata.

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

  Completeness5/5

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

  Given the single parameter, presence of annotations covering safety hints, and no output schema, the description is complete. It covers the action, mechanism, side effects, usage context, and data preservation guarantees—sufficient for an agent to invoke this simple archival tool correctly.

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

  Parameters3/5

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

  The input schema has 100% description coverage ('Unique UUID identifier of the active project record to archive'), so the description does not need to duplicate parameter details. It implicitly references the project_id by mentioning 'a project' but adds no additional parameter syntax or semantics beyond the schema.

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

  Purpose5/5

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

  The description explicitly states 'Soft-delete a project by setting its archived_at timestamp', providing a specific verb, resource, and mechanism. It distinguishes this from permanent deletion by emphasizing 'preserving all historical data' and 'without permanently destroying its records', clearly differentiating it from hard-delete alternatives.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance: 'when a freelancer wants to close out a completed or cancelled project'. It also implies when-not-to-use by specifying 'without permanently destroying its records', though it doesn't explicitly name the alternative tool for hard deletion if one exists.

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

• projects.records.listA
  4.3/5.0
  Behavior4/5

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

  Annotations declare read-only/non-destructive safety. Description adds critical behavioral scope ('non-archived' filter) not present in annotations, plus pagination context. Does not contradict annotations.

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

  Conciseness5/5

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

  Two sentences with zero waste: first establishes function and features, second establishes user context. Front-loaded with action verb and appropriately sized for parameter complexity.

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

  Completeness5/5

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

  Given 100% schema coverage, comprehensive annotations, and no output schema, the description adequately covers tool scope (non-archived constraint), user persona (freelancer), and operational context (portfolio overview vs. search).

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

  Parameters3/5

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

  Schema coverage is 100%, so parameters are fully documented structurally. Description groups parameters semantically ('filters, sorting, and pagination') but adds no syntax, format, or dependency details beyond schema definitions.

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

  Purpose5/5

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

  The description opens with specific verb 'List' and resource 'non-archived projects', explicitly distinguishing scope from sibling 'projects.records.archive'. It enumerates capabilities (full-text search, filters, sorting, pagination) providing precise functional coverage.

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

  Usage Guidelines4/5

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

  Second sentence provides explicit when-to-use guidance ('when a freelancer wants an overview... or needs to locate'). Lacks explicit contrast with 'projects.records.get' for direct ID lookups vs. searching, though the intent is implied.

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

• proposals.records.getA
  4.3/5.0
  Behavior4/5

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

  Annotations cover safety profile (readOnly/idempotent). The description adds valuable behavioral context about return values ('returning all stored fields including status, amount, and content'), compensating for the missing output schema. Does not mention error behavior for invalid IDs, but openWorldHint=false implies strict validation.

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

  Conciseness5/5

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

  Two well-structured sentences with zero waste. First sentence defines action and return payload; second defines usage trigger. Front-loaded with the most critical information (single record retrieval by ID).

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

  Completeness5/5

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

  For a simple single-parameter read operation, the description is complete. It compensates for the lack of output schema by describing returned fields (status, amount, content), and works with the comprehensive annotations and fully-documented schema to provide sufficient context for invocation.

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

  Parameters3/5

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

  Schema has 100% description coverage with detailed UUID pattern and format. The description references 'unique identifier' which aligns with the proposal_id parameter semantics, but adds no additional syntax guidance or validation rules beyond the comprehensive schema.

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

  Purpose5/5

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

  The description uses specific verb 'Retrieve' with clear resource 'single proposal' and scope 'by its unique identifier'. It distinguishes from sibling proposals.records.list by emphasizing 'single' vs listing, and from write operations (create/update/accept) by using 'Retrieve'.

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

  Usage Guidelines4/5

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

  Provides clear when-to-use context ('when the freelancer asks to view, review, or reference'). However, it lacks explicit when-not-to-use guidance or named alternatives (e.g., not mentioning to use proposals.records.list for searching instead of specific ID lookups).

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

• scope.definition.checkA
  4.3/5.0
  Behavior4/5

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

  Annotations declare read-only, non-destructive, and idempotent properties. Description adds valuable context about what data is accessed ('full change history' alongside current definition) and the intended analytical purpose ('assess whether...'). Does not contradict annotations. Could improve by mentioning if this generates a recommendation or just returns raw data for manual assessment.

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

  Conciseness5/5

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

  Two perfectly structured sentences: first establishes function and data retrieved, second provides usage conditions. No redundancy or filler. Every word earns its place.

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

  Completeness3/5

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

  Description adequately covers intent and parameters, but lacks information about return values or output format given no output schema exists. Does not clarify whether the tool returns a boolean verdict, a textual analysis, or raw scope documents requiring interpretation, leaving a gap for the agent's expectations.

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

  Parameters3/5

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

  Input schema has 100% description coverage with detailed explanations for both project_id ('against whose scope the new request should be assessed') and request_description. Description reinforces the semantic relationship between parameters but adds no new technical details beyond what the schema provides, warranting the baseline score for high-coverage schemas.

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

  Purpose5/5

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

  Description provides specific verb ('Retrieve'), clear resources ('agreed scope definition and full change history'), and explicit purpose ('assess whether a new client request falls within the original agreement'). It clearly distinguishes from sibling scope.definition.get by emphasizing the assessment/comparison function rather than simple retrieval.

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

  Usage Guidelines5/5

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

  Excellent explicit guidance: '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.' Provides clear trigger condition (client asks for something new) and decision context (before responding).

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

• followups.context.getA
  4.4/5.0
  Behavior4/5

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

  Annotations already confirm read-only, non-destructive, idempotent behavior. The description adds valuable behavioral context that this tool aggregates data across multiple sources (invoices, message history, contact records) and serves as a prerequisite dependency for drafting operations. 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.

  Conciseness5/5

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

  Two sentences, zero waste. First sentence defines scope and data sources; second sentence provides critical workflow sequencing. Every word earns its place and the description is appropriately front-loaded with the action verb.

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

  Completeness4/5

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

  Despite lacking an output schema, the description adequately compensates by enumerating the specific data categories returned (invoices, history, contact info). For a read-only aggregation tool with well-documented inputs, the description provides sufficient context for correct invocation, though explicit mention of the return structure would elevate this to 5.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both client_id and project_id fully documented in the schema itself. The main description mentions 'client' generally but does not elaborate on parameter semantics beyond what the schema already provides, which is appropriate given the high schema coverage.

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

  Purpose5/5

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

  The description uses a specific verb ('Fetch') and clearly identifies the resource (context for drafting follow-ups). It explicitly lists the three data components retrieved (outstanding invoices, recent follow-up history, contact details), distinguishing it from generic 'get client' tools in the sibling list.

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

  Usage Guidelines5/5

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

  Provides explicit workflow guidance: 'Always call this tool before followups.create' with the rationale 'so the drafted message is informed by the client's current account status.' This establishes clear sequencing with the sibling followups.messages.create tool and explains the prerequisite relationship.

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

• proposals.records.updateA
  4.4/5.0
  Behavior4/5

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

  Annotations declare idempotentHint=true and destructiveHint=false. Description adds valuable behavioral context that this is a partial update ('one or more fields') rather than full replacement, and specifies workflow semantics (marking sent, recording responses). Does not contradict annotations.

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

  Conciseness5/5

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

  Two sentences with zero waste. First sentence defines capability, second defines usage context. Front-loaded with the core action and efficiently structured.

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

  Completeness4/5

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

  Appropriately complete for a 9-parameter update operation. Combines comprehensive schema annotations, clear idempotency/destructive hints, and workflow guidance. Lacks explicit mention of return value or error behavior on missing proposal_id, but this is minor given standard REST conventions.

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

  Parameters3/5

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

  Schema coverage is 100% with detailed parameter descriptions. Description provides high-level semantic grouping ('content, pricing, status, or key timestamps') mapping to the 9 parameters, but does not add syntax, format, or constraint details beyond the schema. Baseline 3 appropriate for high-coverage schema.

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

  Purpose5/5

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

  States specific action ('Update one or more fields') on specific resource ('existing proposal') and enumerates field categories (content, pricing, status, timestamps). Clearly distinguishes from sibling tool 'proposals.records.accept' by specifying this avoids the 'full accept flow'.

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

  Usage Guidelines5/5

  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') and contrasts with alternative workflow ('without going through the full accept flow'), providing clear decision criteria against the sibling accept tool.

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

• scope.changes.logA
  4.4/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=false and destructiveHint=false. The description adds business context by stating it maintains an 'auditable history,' implying persistence and immutability. It also warns against speculative use, implying records cannot be easily undone. However, it doesn't explicitly confirm that multiple calls create duplicate entries (though idempotentHint=false covers this) or mention if notifications are triggered.

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

  Conciseness5/5

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

  Two sentences, both essential. The first establishes purpose and value proposition; the second provides critical usage guardrails. No redundant text or tautology. Information is front-loaded with the action verb.

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

  Completeness4/5

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

  Given the 100% schema coverage and clear annotations, the description provides sufficient context for a 6-parameter tool. It covers the business domain (scope creep auditing) and critical workflow constraints. Minor gap: does not explicitly describe the return value or confirmation that a record was created, though 'auditable history' implies success.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is 3. The description references 'classification and impact notes,' acknowledging key parameters, but does not add semantic details, format guidance, or examples beyond what the comprehensive schema already provides.

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

  Purpose5/5

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

  The description opens with the specific action 'Record a client scope change request' and clearly identifies the resource (scope change) and purpose (maintain auditable history of scope creep). It effectively distinguishes from siblings like scope.definition.* (defining scope vs. logging changes) and scope.changes.list (viewing vs. recording).

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

  Usage Guidelines5/5

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

  Provides explicit constraints: 'Use this tool ONLY after the freelancer confirms' and 'never log speculatively without explicit instruction.' This clearly defines both when to use (explicit confirmation required) and when not to use (speculative logging), preventing erroneous invocations.

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

• clients.records.archiveA
  4.5/5.0
  Behavior5/5

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

  Excellently supplements annotations. While annotations flag destructiveHint=true, the description crucially clarifies this is a 'soft-delete' (not permanent data loss), explains the cascading visibility impact on linked projects/invoices/follow-ups, and notes idempotent behavior implied by timestamp-setting.

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

  Conciseness5/5

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

  Two dense sentences with zero redundancy. Front-loaded with the core action (soft-delete mechanism), followed immediately by usage context and cascading effects. Every clause conveys distinct information about behavior or usage.

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

  Completeness5/5

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

  For a single-parameter archive operation, the description comprehensively covers the mechanism (timestamp setting), visibility semantics (hidden from normal queries), data persistence (auditable history), and relational impact (linked entities remain). No output schema exists, but the description adequately explains the state change.

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

  Parameters3/5

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

  Schema has 100% description coverage for the single client_id parameter. The description text refers to 'a client' generally but does not add parameter-specific details (format hints, examples) beyond what the schema already provides, meeting the baseline for fully-documented schemas.

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

  Purpose5/5

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

  The description explicitly states 'Soft-delete a client by setting their archived_at timestamp,' providing a specific mechanism (soft-delete), resource (client), and differentiating it from siblings like 'update' or hard delete by emphasizing preservation of full history.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance ('when a freelancer is done working with a client and wants to retire the record') and explains consequences (hides from normal queries but preserves audit trail). Lacks explicit mention of alternative tools (e.g., 'use update instead for status changes'), but the use case context is clear.

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

• clients.records.getA
  4.5/5.0
  Behavior4/5

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

  Annotations declare readOnly/idempotent hints, so the description appropriately focuses on data scope rather than safety, explaining that the return includes 'all associated projects and follow-up communications' which adds necessary context about the richness of the response.

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

  Conciseness5/5

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

  Two well-structured sentences with zero waste: first sentence states the core action and data scope, second provides usage triggers. Information is front-loaded and every clause earns its place.

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

  Completeness5/5

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

  Given the simple single-parameter input, comprehensive annotations covering behavioral traits, and the description's explanation of what data is returned (compensating for lack of output schema), the definition is complete for this tool type.

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

  Parameters4/5

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

  With 100% schema coverage, the baseline is 3. The description adds value by specifying the lookup context ('by name or ID') guiding the agent on when to invoke the tool, even though the schema strictly requires the UUID format.

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

  Purpose5/5

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

  The description uses specific verbs ('Retrieve') and resources ('full profile for a single client') and clearly distinguishes from sibling tools like 'list' by emphasizing 'single client' and specific scope ('including all associated projects and follow-up communications').

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use triggers ('when a freelancer asks about a specific client', 'when you need complete client context before drafting...'), but does not explicitly name the 'clients.records.list' alternative for searching multiple clients.

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

• time.entries.archiveA
  4.5/5.0
  Behavior5/5

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

  Excellently supplements annotations by detailing the exact mechanism (timestamp setting), immediate effect ('hiding it from all queries'), and data preservation guarantee. Explains the idempotent nature implied by 'setting' a timestamp and clarifies that 'destructive' applies to visibility, not data integrity.

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

  Conciseness5/5

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

  Two tightly constructed sentences with zero redundancy. Front-loaded with the action and mechanism, followed immediately by use-case guidance. Every clause earns its place.

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

  Completeness5/5

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

  Given the simple single-parameter schema and presence of rich annotations (destructiveHint, idempotentHint), the description successfully covers the mechanism, side effects, and use cases without needing to describe return values (no output schema).

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

  Parameters3/5

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

  With 100% schema description coverage for the single UUID parameter, the schema fully documents the input. The description provides baseline adequacy by referencing 'time entry' contextually but does not add syntax or format guidance beyond the schema.

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

  Purpose5/5

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

  Description uses specific verb phrase 'Soft-delete' with explicit mechanism ('setting its archived_at timestamp') and resource ('time entry'). The 'without destroying the underlying data' clause effectively distinguishes this from hard-delete patterns.

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

  Usage Guidelines4/5

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

  Provides explicit when-to-use guidance ('when the freelancer wants to permanently remove an incorrectly logged or duplicate time entry'), distinguishing archiving for removal from editing workflows. Lacks explicit mention of sibling alternatives like 'update', but the use case implies replacement rather than modification.

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

• clients.records.createA
  4.7/5.0
  Behavior4/5

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

  Annotations indicate non-destructive write (readOnlyHint:false, destructiveHint:false). The description adds valuable workflow context: captured data 'saves time when creating projects and invoices later,' explaining the tool's role in the broader system. Missing only idempotency specifics (though annotations cover idempotentHint:false).

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

  Conciseness5/5

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

  Two sentences, zero redundancy. First sentence defines the action; second provides usage trigger and business justification. Every clause earns its place.

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

  Completeness5/5

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

  Given 7 parameters with full schema coverage and no output schema, the description is complete. It addresses the domain (FreelanceOS), trigger conditions, and integration with sibling workflows (projects/invoices).

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

  Parameters4/5

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

  With 100% schema coverage, baseline is 3. The description adds conceptual grouping ('contact details,' 'default billing rate') and strategic purpose ('upfront... saves time later'), providing semantic value beyond the technical schema definitions.

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

  Purpose5/5

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

  The description opens with a precise action ('Create a new client record') and specific resource ('FreelanceOS database'). It distinguishes from siblings by specifying this is for 'new' clients and contrasting with downstream tools (projects/invoices).

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

  Usage Guidelines5/5

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

  Explicitly states when to use: 'whenever a freelancer mentions a new client they're starting to work with or want to begin tracking.' This clearly differentiates from update/archive siblings and establishes trigger conditions for the agent.

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