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

With no annotations provided, the description carries the full burden. It discloses that it creates a new record and returns it, which covers basic behavior, but lacks details on permissions, error handling, rate limits, or side effects. It adequately describes the core operation but misses advanced behavioral traits.

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

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

The description is front-loaded with the core purpose, followed by key details on required/optional parameters and return value in just two sentences. Every sentence adds essential information without redundancy, making it highly efficient and well-structured.

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

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

For a creation tool with no annotations and no output schema, the description is reasonably complete: it explains what the tool does, key parameters, and the return value. However, it could improve by addressing permissions or error scenarios, given the mutation nature and lack of structured safety hints.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value by reiterating that 'Only the company name is required' and listing optional fields, but does not provide additional context beyond what the schema specifies, such as format constraints or usage examples.

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

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

The description clearly states the specific action ('Create a new company'), the target resource ('in Attio CRM'), and distinguishes it from siblings like 'update_company' or 'search_companies' by focusing on creation rather than modification or retrieval.

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

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

The description implies usage by stating 'Only the company name is required' and listing optional fields, but it does not explicitly guide when to use this tool versus alternatives like 'update_company' or 'search_companies', nor does it mention prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It mentions that the tool creates a new note and supports plaintext/markdown formatting, but does not disclose behavioral traits like required permissions, whether the operation is idempotent, error handling, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

The description is appropriately sized with two sentences that are front-loaded with the main purpose. Each sentence earns its place by specifying the tool's function and format support, though it could be slightly more structured (e.g., separating usage notes).

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

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

Given that this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., permissions, side effects), response format, or error conditions. While the schema covers parameters well, the overall context for safe and effective use is insufficient.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning attachment to records and format support, but does not provide additional syntax, examples, or constraints. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the verb ('Create') and resource ('a new note attached to a record in Attio CRM'), specifying that notes can be attached to people, companies, or other object types. It distinguishes from sibling tools like create_company or create_person by focusing specifically on notes rather than creating records themselves.

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

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

The description implies usage by mentioning attachment to records and supported formats, but does not explicitly state when to use this tool versus alternatives (e.g., when to attach a note vs. updating a record directly). It provides some context but lacks explicit guidance on exclusions or comparisons with sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal that the tool creates a new record (mutation operation) and specifies the return value ('Returns the created person record including the new record_id'). However, it doesn't mention permission requirements, rate limits, error conditions, or what happens with duplicate entries.

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

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

The description is perfectly sized at three sentences with zero waste. It's front-loaded with the core purpose, followed by critical constraints, and ends with the return value. Every sentence earns its place by providing essential information for tool selection and invocation.

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

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

For a mutation tool with no annotations and no output schema, the description does a good job covering the essentials: purpose, constraints, and return value. However, it could be more complete by addressing potential side effects (like auto-creation of new tags mentioned in the schema) and error scenarios. The 100% schema coverage helps compensate for some gaps.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds value by explaining the logical constraint that 'you need either a name or email to identify the person' and clarifying that 'All fields are optional' except for this constraint. This provides important semantic context beyond the schema's technical documentation.

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

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

The description clearly states the specific action ('Create a new person in Attio CRM'), identifies the resource ('person'), and distinguishes it from siblings like 'create_company' or 'create_note' by specifying it's for person records. It goes beyond just restating the name by explaining what the tool actually does.

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

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

The description provides clear context about when to use this tool ('Create a new person') and includes important prerequisites ('You must provide at least one name field or at least one email address'). However, it doesn't explicitly state when NOT to use it or mention alternatives like 'update_person' for existing records.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns data (read operation) and describes optional inclusion of related data, but lacks details on permissions, rate limits, error handling, or response format. It adds some behavioral context but not comprehensively.

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

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

The description is front-loaded with the core purpose, followed by concise details on optional parameters. Both sentences are necessary and efficient, with zero wasted words.

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

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

Given no annotations and no output schema, the description adequately covers the tool's purpose and parameters but lacks information on return values, error cases, or operational constraints. It is minimally complete but has clear gaps for a read tool with multiple options.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by mentioning include_all and individual flags, but does not provide additional meaning beyond what the schema specifies. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Get') and resource ('company'), specifies what is returned ('complete details', 'all attributes'), and distinguishes it from siblings by focusing on retrieving a single company by ID rather than searching or creating.

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

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

The description provides clear context for when to use this tool (to fetch details of a specific company by record_id) and hints at alternatives (individual flags vs. include_all), but does not explicitly state when not to use it or compare it to sibling tools like search_companies.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns full note details including specific fields (title, content, parent record, creation metadata), which adds useful context beyond a basic read operation. However, it lacks details on error handling, permissions, or rate limits, leaving gaps for a tool with no 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.

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and return details. It is front-loaded with the core action and resource, followed by specifics on the output, with no redundant or unnecessary information. Every part of the sentence adds value.

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

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

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is adequate but incomplete. It explains what the tool does and what it returns, which is sufficient for basic use. However, without annotations or output schema, it could benefit from more behavioral details like error cases or response structure to fully guide the agent.

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

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

The input schema has 100% description coverage, with the note_id parameter fully documented in the schema. The description does not add any parameter-specific information beyond what the schema provides, such as format examples or constraints. Baseline score of 3 is appropriate since the schema handles the parameter documentation adequately.

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

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

The description clearly states the action ('Get'), resource ('a single note'), and method ('by ID from Attio CRM'), distinguishing it from sibling tools like create_note or search_people. It specifies retrieving a single note rather than listing or creating, making the purpose explicit and distinct.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like get_company or get_person for similar retrieval operations, nor does it specify prerequisites such as needing a note ID or when this is appropriate over search functions. Usage context is implied but not stated.

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

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

With no annotations provided, the description carries full burden. It discloses the tool's read-only nature implicitly ('Get', 'Returns'), but doesn't mention authentication needs, rate limits, error conditions, or response format. It adds some context about optional data inclusion, but lacks comprehensive behavioral details for a tool with 7 parameters.

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

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

Two sentences with zero waste: first states core purpose, second explains optional data inclusion. Every word earns its place, and the structure is front-loaded with the primary function.

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

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

For a read-only tool with 7 parameters and no output schema, the description adequately covers the basic purpose and parameter usage. However, without annotations or output schema, it lacks details on return format, error handling, and performance considerations that would be helpful given the complexity of optional data inclusion.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value by mentioning include_all and individual flags, but doesn't provide additional semantics beyond what's in the schema (e.g., performance implications of include_all). Baseline 3 is appropriate when schema does heavy lifting.

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

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

The description clearly states the specific action ('Get complete details') and resource ('a person'), distinguishing it from sibling tools like search_people (which lists multiple people) or update_person (which modifies). It explicitly mentions fetching by record_id and returning all attributes.

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

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

The description implies usage for retrieving detailed person data, including optional related data via flags, but doesn't explicitly state when to use this vs. alternatives like search_people for broader queries or get_company for different entity types. No explicit exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it's a read operation (implied by 'Get'), explains caching behavior ('Bypass cache' via force_reload), and details output variations based on scope. However, it doesn't mention potential rate limits, error conditions, or authentication needs, leaving some behavioral aspects uncovered.

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

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

The description is perfectly concise and front-loaded: the first sentence states the core purpose, followed by specific usage instructions. Every sentence earns its place by providing essential information about defaults, scope options, and parameter requirements without any redundant or vague language.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is nearly complete. It covers purpose, usage guidelines, parameter semantics, and some behavioral aspects. The main gap is lack of information about return values/output format, which would be helpful since there's no output schema. However, it provides sufficient context for effective use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the semantic meaning of scope options beyond the schema's enum values: it clarifies what 'summary', 'full', 'object', and 'list' actually retrieve in practice (e.g., 'key fields only', 'all fields'), providing context that enhances parameter understanding beyond the structured schema.

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

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

The description clearly states the verb ('Get') and resource ('Attio workspace schema'), specifying what data is retrieved. It distinguishes from sibling tools (which focus on specific entities like companies/people) by targeting schema metadata rather than entity data, making its purpose specific and differentiated.

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

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

The description provides explicit guidance on when to use different scope values: 'summary' for key fields, 'full' for all fields, and 'object'/'list' for specific items with all fields. It clearly explains the default behavior and conditions for using optional parameters (e.g., object_slug required for scope='object'), offering complete usage context.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It describes the four operations but doesn't mention permission requirements, whether changes are reversible, rate limits, or what happens to existing domains during operations. For a mutation tool with zero annotation coverage, this is inadequate.

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

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

The description is extremely concise and front-loaded: a single sentence that efficiently communicates the tool's scope and all four operations. Every word earns its place with zero waste.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or important behavioral details like whether operations are atomic. The 100% schema coverage helps, but the description should do more for a tool that modifies company data.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value by listing the four operation types, which is already covered in the schema's enum description. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Manage domains on a company' with specific operations (set, add, remove, clear). It distinguishes from siblings like manage_person_emails by specifying the resource (company domains), but doesn't explicitly differentiate from other company tools like update_company.

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

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

The description provides no guidance on when to use this tool versus alternatives like update_company or other company management tools. It lists operations but offers no context about appropriate scenarios, prerequisites, or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the four operations but lacks critical details: whether changes are permanent/reversible, what permissions are required, if there are rate limits, or what happens on success/failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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

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

The description is a single, efficient sentence that front-loads the core purpose and enumerates all operations without waste. Every word earns its place, making it easy for an agent to parse quickly. No extraneous information or redundancy is present.

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

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

Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., success status, updated person object), error conditions, or side effects. For a tool that modifies data, this lack of behavioral and output context is inadequate.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by listing the same four operations and noting that 'email_addresses' is not required for 'clear'. This meets the baseline for high schema coverage but doesn't provide additional semantic context.

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

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

The description clearly states the tool's purpose: 'Manage email addresses on a person' with specific operations (set, add, remove, clear). It distinguishes itself from sibling tools like 'manage_person_tags' by focusing on emails rather than tags. However, it doesn't explicitly differentiate from other person-related tools like 'update_person', which might also handle email updates.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'update_person' or 'create_person'. It lists operations but doesn't specify prerequisites (e.g., needing a valid record_id) or contextual cues for choosing between operations. This leaves the agent without clear decision-making criteria.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it describes the four distinct operations, mentions that tags are auto-created if they don't exist, and implies this is a mutation tool. It could improve by mentioning permissions or error conditions.

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

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

Two sentences with zero waste - the first sentence states the purpose and operations, the second adds important behavioral context about tag auto-creation. Every element earns its place and the information is front-loaded.

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

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

For a mutation tool with no annotations and no output schema, the description does well by explaining operations and tag behavior. It could be more complete by mentioning what the tool returns or error scenarios, but covers the essential context given the complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some context about tag auto-creation and workspace matching, but doesn't provide significant additional parameter semantics beyond what's in the schema.

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

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

The description clearly states the specific verb ('manage') and resource ('tags on a person'), with explicit mention of the four supported operations. It distinguishes this tool from sibling tools like update_person or manage_person_emails by focusing exclusively on tag operations.

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

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

The description provides clear context for when to use this tool (for tag management on people) and implicitly distinguishes it from other person-related tools. However, it lacks explicit guidance on when not to use it or named alternatives for similar operations.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions filtering, sorting, and return details, but lacks critical behavioral traits such as pagination handling (beyond the limit parameter), rate limits, authentication requirements, error conditions, or whether this is a read-only operation (though implied by 'Search'). For a search tool with no annotations, this leaves significant gaps in understanding its behavior.

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

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

The description is appropriately sized and front-loaded, with the first sentence stating the core purpose. Each subsequent sentence adds specific, non-redundant information about filtering, sorting, and return details, with zero waste or unnecessary elaboration.

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

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

Given the tool's moderate complexity (6 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose and basic functionality but lacks behavioral context like pagination, error handling, or performance limits. Without annotations or an output schema, more detail on return structure or operational constraints would improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning filtering by text and date ranges, but doesn't provide additional syntax, format details, or usage examples. This meets the baseline score of 3 when the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Search for companies'), resource ('in Attio CRM'), and scope ('Supports filtering by text... and date ranges'). It distinguishes this tool from siblings like get_company (which retrieves a single company) and search_people (which searches for people instead of companies).

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

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

The description implies usage context through 'Supports filtering...' and 'All filters are optional,' suggesting this is for flexible company searches. However, it doesn't explicitly state when to use this tool versus alternatives like get_company (for specific IDs) or create_company (for new entries), nor does it mention any prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that 'All filters are optional' and describes the return format, which is helpful. However, it omits critical behavioral details such as pagination handling (beyond the limit parameter), rate limits, authentication requirements, error conditions, or whether this is a read-only operation—significant gaps for a search tool with multiple parameters.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose and key features in a single, efficient sentence. A second sentence adds return details, which is useful but could be slightly more streamlined. Overall, it avoids unnecessary fluff and communicates essential information without waste.

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

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

Given the complexity (9 parameters, no annotations, no output schema), the description is partially complete. It covers the purpose, filters, and return fields adequately, but lacks details on behavioral aspects like pagination, errors, or performance limits. Without annotations or an output schema, the agent might struggle with full operational understanding, though the description provides a reasonable foundation.

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

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

The description adds some context by listing filter types (text, company, tags, date ranges) and sorting, but the input schema already has 100% coverage with detailed descriptions for all 9 parameters. The description does not provide additional syntax, examples, or constraints beyond what the schema specifies, so it meets the baseline for high schema coverage without adding substantial value.

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

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

The description clearly states the specific verb ('Search for people') and resource ('in Attio CRM'), distinguishing it from sibling tools like create_person, get_person, update_person, and manage_person_tags. It specifies the search functionality with filtering capabilities, making the purpose unambiguous and differentiated from related operations.

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

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

The description implies usage through its listing of supported filters (text, company, tags, date ranges) and sorting, suggesting when this tool might be appropriate. However, it lacks explicit guidance on when to use search_people versus alternatives like get_person (for specific records) or create_person (for new entries), leaving some ambiguity for the agent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a mutation operation (implied by 'update'), uses partial updates ('Only provided fields will be updated; omitted fields remain unchanged'), and specifies the return value ('Returns the updated company record'). However, it lacks details on permissions, error handling, or rate limits.

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

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

The description is efficiently structured in three sentences: the core purpose, behavioral detail on partial updates, and usage guidance with alternatives. Every sentence adds value without redundancy, and it's front-loaded with the main action.

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

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

Given the mutation nature, 4 parameters, no annotations, and no output schema, the description does well by covering purpose, partial update behavior, domain management alternatives, and return value. However, it could improve by mentioning prerequisites (e.g., needing a valid record_id) or error scenarios, leaving minor gaps for a tool with no structured safety hints.

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

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

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by listing the updatable fields (name, description, LinkedIn URL) and mentioning the record_id requirement, but doesn't provide additional syntax or format details. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Update an existing company'), the target resource ('in Attio CRM by record ID'), and distinguishes it from sibling tools like create_company and get_company. It specifies the updatable fields (name, description, LinkedIn URL), making the purpose unambiguous and differentiated.

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

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

The description provides explicit guidance on when to use this tool ('update an existing company by record ID') and when not to use it for related tasks ('To manage domains, use add_company_domain and remove_company_domain tools instead'). It also implicitly distinguishes it from create_company for new records and get_company for reading.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains the partial update behavior ('Only provided fields will be updated; omitted fields remain unchanged') and the return value ('Returns the updated person record'), which are crucial for understanding the tool's effects. However, it doesn't mention potential error conditions, permissions, or rate limits.

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

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

The description is efficiently structured in three sentences: first states purpose and scope, second explains update behavior, third provides usage guidance and return value. Every sentence adds essential information with zero wasted words, making it easy to parse.

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

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

For a mutation tool with no annotations and no output schema, the description does well by explaining the partial update behavior, return value, and alternative tools. However, it could be more complete by mentioning authentication requirements, error handling, or what constitutes a valid record_id. The absence of output schema means the description should ideally detail the return structure more explicitly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value by listing the updatable fields ('name fields, description, and/or LinkedIn URL'), but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Update an existing person'), target resource ('in Attio CRM'), and mechanism ('by record ID'), distinguishing it from sibling tools like create_person (for creation) and get_person (for retrieval). It precisely defines the scope of the operation.

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

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

The description provides explicit guidance on when to use alternatives: 'To manage email addresses, use add_person_email and remove_person_email tools instead.' This clearly delineates the tool's scope from related sibling tools, helping the agent choose correctly.

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