SMI Aware Assistant

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations by specifying that the returned record is the 'full' record and by requiring that the id come from a search result, which prevents misuse. This is meaningful but not extensive, hence 4 rather than 3.

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

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

Three sentences, each contributing distinct information: what it does, the critical constraint on the input, and the alternative tools for other id forms. The main purpose is front-loaded, and there is no filler or repetition.

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

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

For a single-parameter read-only tool with an output schema and full annotation coverage, the description covers use case, input provenance, exclusions, and alternatives. Nothing an agent needs to call it correctly is missing, and output details are already provided by the output schema.

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

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

Schema coverage is 100%, with the 'id' property described as a typed reference with an example. The description adds value by explaining the id format ('<type>:<id>') and explicitly requiring that the id be one returned by search, which constrains how the parameter is sourced. That goes beyond the schema's basic type description.

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

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

The description names a specific verb ('fetches') and resource ('full SMI record') plus the exact input form ('<type>:<id>') and its origin (search results). It explicitly distinguishes this tool from sibling readers like smi_get_deep_report and smi_get_export, making its role unambiguous.

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

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

It states exactly when to use the tool ('for a typed reference that search returned') and when not to ('Pass only an id that appeared in a search result; do not construct one'). It also names concrete alternatives for plain SMI record ids, giving clear routing guidance among siblings.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that the tool runs locally, makes no network calls, and never reads or requires credentials. This is important behavioral context that is not available in the annotations alone.

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

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

The description is compact and front-loads the core purpose and precondition. Every sentence contributes either behavioral context, parameter semantics, or routing guidance without redundancy.

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

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

For a single-optional-parameter helper with no output schema, the description fully covers the call flow: first call with no input, second call with hasToken, and the resulting guidance paths. No missing information would prevent an agent from invoking it correctly.

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

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

The schema already documents hasToken with an enum, but the description adds meaningful semantics: hasToken 'yes' leads to connect guidance and verify_access, while 'no' leads to prospect-intake guidance. It also clarifies that omitting the parameter returns the fork question.

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 is a pre-connection onboarding helper that returns a fork question and provides token-based guidance. It is explicitly distinguished from siblings by describing the connection and prospect-intake paths and by referencing verify_access as the next step.

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

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

It says call this before any SMI token is set, with no input to get the fork question, then call again with hasToken 'yes' or 'no' for the appropriate guidance. It also points to verify_access for the connect path, giving clear routing among related tools.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses meaningful behavior: deep reports and research bundles are filtered server-side by subject first/last name, then broaden to an unfiltered client-side ranked fetch across id, name, url, and summary when nothing is found. It also explains that exports match on url. This level of transparency helps an agent predict result scope and fallback 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 long but every sentence carries necessary routing or behavioral information. The core purpose is front-loaded, the alternative tool routing is compressed into one sentence, and the filtering/fallback behavior is stated precisely. There is no filler or repetition.

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

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

For a discovery tool with one parameter, an output schema, and rich annotations, the description is complete: it states what is searched, how results are ranked/fallback, how exports differ, and which sibling tools to use instead. The only implicit details are likely covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline for parameter semantics is 3. The description adds value by specifying that the query can be a subject name, url, or keyword, and that exports match specifically on url. This enriches the schema's generic 'Free-text search query' example without being redundant.

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

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

The description opens with a specific verb and resource: open-ended discovery across SMI deep reports, research bundles, and exports. It explicitly scopes the tool to cases where the caller does not already have a record id, and it distinguishes search from fetch and the smi_get_* tools. This makes the purpose unambiguous and clearly separated from siblings.

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

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

The description gives explicit when-to-use guidance: use search for open-ended discovery without a record id. It then names concrete alternatives for the case where a record id already exists, listing smi_get_deep_report, smi_get_export, smi_check_order_complete, smi_list_deep_reports, smi_list_exports, and smi_get_report_findings. This is strong routing guidance that leaves little to inference.

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

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

The description adds no behavioral context beyond what annotations already provide. It does not explain whether the address is appended or replaces an existing one, whether the subject must already exist, or any side effects. Since annotations already mark the operation as non-read-only, non-idempotent, and non-destructive, no additional credit is earned.

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, front-loaded sentence that directly states the operation with no filler, redundancy, or unnecessary detail. Every word earns its place.

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

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

With a fully described input schema and an output schema present, the minimal description is mostly adequate for a simple add-address operation. However, it omits usage context and behavioral nuances, such as how this relates to existing addresses or to the update_subject sibling, leaving 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?

All 9 parameters are fully described in the schema (100% coverage), so the description does not need to explain parameters. It adds no parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description names a specific action ('attaches') and resource ('postal address') directed at an 'SMI subject', and the resource clearly distinguishes it from the many smi_add_subject_* siblings (phone, email, alias, etc.). It is unambiguous and immediately actionable.

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

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

No usage context is provided. The description does not state when to prefer this tool over smi_update_subject or any sibling, nor does it give exclusions or alternatives. An agent must infer applicability from the tool name alone.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the mutation and non-idempotent behavior are known. The description adds no extra behavioral context, such as whether duplicate aliases are allowed, whether existing aliases are preserved, or any side effects beyond the annotation metadata.

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, focused sentence with no filler, making it easy to parse. It is not scored higher because it omits useful usage or behavioral details that would make it more valuable.

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

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

For a simple two-parameter mutation tool with annotations and an output schema, the description is minimally adequate. However, it leaves clear gaps around when to use this tool vs. siblings and what happens on duplicate aliases, so it is not fully complete.

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

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

The description itself adds no parameter-level meaning, but the schema has 100% coverage with clear descriptions for both subjectId and alias. This matches the baseline score for a tool whose schema already documents its parameters 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 states a specific action ('Attaches an alias') and a specific resource ('an SMI subject'), so the core purpose is clear. It does not explicitly distinguish this tool from sibling tools like smi_add_subject_surname, but the verb and object are sufficient to identify the intended 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 no guidance on when to use this tool versus the many other smi_add_subject_* siblings, nor does it state exclusions or prerequisites. The only prerequisite hint ('from a prior smi_get_subject...') appears in the schema, not in the description.

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

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

Annotations already communicate that this is a write operation (readOnlyHint=false), and the description adds little beyond that. It does not disclose idempotence implications, whether duplicate entries are created, what happens to existing education entries, or any other behavioral trait beyond the schema and annotations.

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

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

The description is a single sentence with no filler. The verb is front-loaded and every word contributes meaning, making it easy to parse quickly.

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

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

Given the 8-parameter schema and output schema, the one-line description is minimally adequate but does not add operational context. It does not explain the workflow around subjectId, the meaning of isCurrent in practice, or the effect of adding multiple education entries. The schema and annotations carry most of the burden here.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not mention any specific parameters, but it also does not need to because the schema already documents all 8 fields, including subjectId, isCurrent, and date ranges.

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

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

The description uses a clear verb ('Attaches') and a specific resource ('educational institution to an SMI subject'). This distinctly separates it from the many sibling smi_add_subject_* tools, which all target different entity types.

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?

When to use the tool is implied by its stated purpose: use it to attach an educational institution to a subject. However, it gives no explicit guidance about alternatives or when not to use it, even though numerous smi_add_subject_* sibling tools exist.

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

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

Annotations already establish that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds no behavioral context beyond the verb 'Attaches' – it does not clarify whether an existing email is replaced, whether duplicates are allowed, or what side effects occur.

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?

A single short sentence with the action and object front-loaded. It contains no redundant or filler content, and every word contributes to understanding the tool's purpose.

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

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

For a simple two-parameter mutation with an output schema and helpful annotations, the description is minimally viable. It covers the core purpose and parameters, but it lacks guidance on duplicate or replacement email behavior, which would help an agent know what to expect when invoking the tool.

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

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

Schema description coverage is 100%, and both parameters are already documented with formats and provenance (subjectId from a prior call). The prose description adds no additional semantic detail, so the schema baseline of 3 applies.

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

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

The description states a specific action ('Attaches') and a specific resource ('an email address to an SMI subject'), which clearly differentiates it from the many sibling smi_add_subject_* tools by the type of data being attached.

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 intended use is implied by the resource name: use this tool when an email needs to be attached to an SMI subject. However, the description does not explicitly state when to prefer this over alternatives or mention prerequisites such as obtaining a valid subjectId, which is left entirely to the parameter schema.

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

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

Annotations already indicate readOnlyHint=false, so the description is not required to restate that it's a write. However, the description adds minimal behavioral context beyond the name: it only adds the COMPANY-type constraint. It does not disclose whether this replaces existing employees, whether it can be called multiple times, or what the response structure implies. Given the presence of annotations, a 3 is fair; it adds a little but not rich context.

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

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

The description is a single sentence with no redundant words. It front-loads the core action and the key constraint. It is appropriately sized given that the schema carries the parameter details.

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 10 parameters and many similar sibling tools, the description is too sparse. It does not mention prerequisites (e.g., subject must exist and be a company), whether it is an additive operation (likely), or how it relates to smi_add_subject_employer. While an output schema exists, the description fails to guide an agent on when to choose this tool over others or what side effects occur. This is a significant gap for a complex mutation.

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

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

Schema coverage is 100%, so all 10 parameters have detailed descriptions in the schema (e.g., subjectId references prior calls, isCurrent asks to clarify with user). The tool description itself adds no parameter-level information. Baseline for high coverage is 3, and the description does not need to compensate.

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

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

The description clearly states the action (attaches an employee), the resource (SMI subject), and a key scope constraint (COMPANY-type subjects). This distinguishes it from sibling add-tools (address, alias, phone, etc.) which target different entity types. The verb 'attaches' is specific and not a tautology of the name.

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

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

The description implies usage by mentioning COMPANY-type subjects, which hints at when to use it, but it does not explicitly state alternatives or exclusions. For example, it does not differentiate from smi_add_subject_employer (which likely handles the reverse relationship) or explain when not to use this tool. The context is present but not fully explicit.

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

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

Annotations already indicate the operation is a non-read-only, non-idempotent write that is not destructive. The description adds the target entity and the dependency on smi_add_subject_employee, but it does not disclose additional behavioral traits such as duplicate handling or whether multiple URLs can be attached. No contradiction with annotations.

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

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

A single sentence front-loads the action and target, then specifies the ID source. There is no filler or repetition.

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

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

For a two-parameter tool with complete schema coverage and an output schema, the description supplies the essential relationship to smi_add_subject_employee and enough context to invoke it correctly. It loses a point only because it leaves the distinction from sibling URL tools implicit.

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

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

Schema description coverage is 100% and both parameters already have meaningful descriptions. The description's mention of subjectEmployeeId being returned from smi_add_subject_employee essentially repeats the schema's parameter description, adding no new semantic information.

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

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

The description uses a specific verb ('Attaches') and names the exact resource, an SMI subject employee, and the ID it operates on. It is clear but does not explicitly differentiate itself from sibling tools like smi_add_subject_url or smi_add_subject_relationship_url, so it stops short of a 5.

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

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

The description gives clear context by stating the URL is attached to a subject employee using the subjectEmployeeId returned by smi_add_subject_employee, implying a sequencing dependency. However, it does not explain when to choose this tool over the sibling URL-add tools, so it lacks explicit exclusions.

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

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

The annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds no behavioral context beyond the word 'Attaches', such as whether this creates a new employer record, how repeated calls behave, or whether the operation is additive or updates existing data. With only minimal annotation coverage, the description carries the burden of explaining side effects, and it does not do so.

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 sentence with no fluff or redundancy, making it concise and front-loaded. It states the essential action immediately. However, given the tool's complexity (8 parameters, many siblings), the brevity borders on under-specification, though this is more a completeness issue than a conciseness flaw.

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

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

Despite having an output schema, the description is incomplete for a write operation with eight parameters and many sibling tools. It does not explain what 'attaches' operationally entails, when to use this versus similar tools, or any constraints or required context. The schema covers parameter syntax but not the broader decision-making context an agent needs to call the tool correctly.

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

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

Schema description coverage is 100%, and the parameter descriptions are detailed, including examples (e.g., 'e.g. 2019') and instructions ('Ask the user directly if it isn't clear from context'). The description itself adds no parameter information, but the baseline for high schema coverage is 3, and the schema adequately covers semantics. No extra value is provided beyond the structured fields.

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

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

The description states a specific verb ('Attaches'), a resource ('an employer'), and a target ('an SMI subject'), so the core purpose is clear. However, it does not explicitly differentiate this tool from the many sibling 'smi_add_subject_*' tools, so an agent must rely on the tool name to disambiguate. This is a clear statement, but not quite the level of explicit sibling differentiation that would earn a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are numerous sibling tools like smi_add_subject_address, smi_add_subject_education, and smi_add_subject_employee, but the description does not mention any conditions, prerequisites, or selection criteria. An agent is left to infer usage solely from the tool name and generic 'add' semantics.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the description doesn't need to restate those. The description adds minimal behavioral context beyond the annotations—it doesn't mention whether attaching a phone number overwrites existing numbers, whether duplicates are allowed, or what the response contains. The output schema exists, which covers return values, but the description itself adds little 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.

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

The description is a single, concise sentence that front-loads the core action. It is appropriately sized for a simple add-operation tool, though it could have used the space to add a note about behavior (e.g., whether multiple phone numbers are allowed).

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

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

For a simple mutation tool with a full output schema and 100% schema parameter coverage, the description is mostly adequate. However, it lacks guidance on edge cases like whether the phone number replaces existing numbers or is appended, and it doesn't clarify the relationship to sibling add-* tools. The annotations cover safety profile, so the main gap is behavioral nuance.

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 (phone, extension, subjectId) with descriptions. The tool description adds no additional parameter meaning beyond what the schema provides. Baseline 3 is appropriate because 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 'Attaches a phone number to an SMI subject' clearly states the verb (attaches), resource (phone number), and target (SMI subject). It distinguishes itself from sibling tools like smi_add_subject_email or smi_add_subject_address by naming the specific data type being added, though it doesn't explicitly contrast with those siblings.

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

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

The description implies usage context: it is for attaching a phone number to a subject, and the sibling list shows many other add-* tools for different data types. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites like needing a prior smi_get_subject call (though the subjectId parameter description hints at this).

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the agent knows this is a mutation. The description adds a behavioral detail—that the relationshipId is sourced from smi_list_relationships—which is useful. It doesn't mention side effects (e.g., non-idempotency) or prerequisites like subject existence, but given the annotations cover the safety profile, a 3 is reasonable.

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 front-loads the purpose and immediately specifies the source of the relationshipId. There is zero redundancy or filler, making it highly concise.

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

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

The tool has 5 parameters (4 required) and an output schema, so the schema covers parameter details and return values. The description provides the core purpose and the prerequisite for relationshipId. It doesn't mention error conditions or additional behavior, but for a simple relationship-attachment tool with annotations covering mutation, this is sufficient.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds a small semantic clarification for relationshipId (its source from smi_list_relationships), which goes beyond the schema. However, it doesn't add anything for the other parameters, so the baseline of 3 stands with a slight bonus.

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

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

The description states a specific verb ('Attaches') and resource ('relationship to an SMI subject'), making it clear what the tool does. It also references the source of the relationshipId, which distinguishes it from other add-subject tools. It doesn't explicitly list all sibling differentiations, but the name and description are sufficiently clear.

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

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

The description provides a key usage hint: the relationshipId must come from smi_list_relationships, implying a prerequisite step. It doesn't explicitly state when not to use this tool (e.g., for addresses or emails), but the tool name and sibling list make that obvious. It gives context without exclusions, so a 4 is appropriate.

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

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

Annotations already signal a mutating, non-idempotent operation, and the description adds a useful precondition that the relationship must already exist. It does not disclose duplicate handling or whether an existing URL is replaced, but the basic side effect is clear.

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?

One tightly worded sentence communicates the action, the target resource, and the required predecessor call. Every phrase earns its place.

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

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

For a simple two-parameter, no-nested-objects mutation with an output schema and adequate annotations, the description covers what the tool does and the key input provenance. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with both url and subjectRelationshipId already explained in the schema. The description only repeats the provenance of subjectRelationshipId and adds no meaning beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb ('attaches') and resource ('a url to an SMI subject relationship'), and clarifies it operates on an existing relationship via subjectRelationshipId. This makes it distinct from sibling tools like smi_add_subject_url, which attaches URLs to a subject rather than a relationship.

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

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

It states when the tool is appropriate: after smi_add_subject_relationship has returned the relationship ID. It does not explicitly enumerate alternatives or exclusions, but the precondition is clear and the sibling set makes the routing obvious.

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

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

The description adds little beyond the annotations: 'Attaches' is consistent with readOnlyHint=false, but it does not explain idempotency implications, duplicate-handling behavior, or any side effects. The openWorldHint and idempotentHint are left unexplained, so the description carries minimal behavioral value.

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

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

A single, front-loaded sentence with no filler words. It is appropriately concise but not quite a 5 because it omits supporting context that would make the definition more independently useful.

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

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

For a simple two-parameter mutation with an output schema and fully documented parameters, the description is minimally workable. However, it lacks usage guidance, behavioral caveats, and differentiation from sibling tools, so the agent must rely heavily on naming conventions and structured metadata.

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

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

Schema description coverage is 100%, and both 'name' and 'subjectId' already have descriptive schema text. The description itself adds no parameter-level detail, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Attaches') and resource ('a surname to an SMI subject'), making the core operation clear. It distinguishes itself from sibling add_subject_address/email/phone tools by naming the surname as the object, though it does not explicitly contrast with add_subject_alias or update_subject.

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?

There is no guidance on when to use this tool versus alternatives, no exclusions, and no prerequisites. Usage is only implied by the tool name and the single action phrase, with no mention of when to prefer smi_add_subject_alias or smi_update_subject.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the description doesn't need to restate those. The description adds minimal behavioral context beyond the annotations—it doesn't mention whether the URL replaces existing URLs, whether duplicates are allowed, or what the response contains. The output schema exists, which covers return values, but the mutation semantics are not disclosed.

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

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

The description is a single, efficient sentence that front-loads the action. It is appropriately sized for a simple tool, though it could have added a brief note about the URL's purpose or the distinction from sibling URL tools without becoming verbose.

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

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

For a simple two-parameter tool with a full output schema and annotations, the description is mostly adequate. However, given the large sibling set of similar 'add' tools, a brief note on when this tool is appropriate versus the URL-specific siblings would improve completeness. The lack of any behavioral detail about the mutation (e.g., append vs. replace) is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional parameter meaning beyond what the schema provides, which is the baseline 3 per the rubric.

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

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

The description states a specific verb ('Attaches') and resource ('a url to an SMI subject'), which clearly identifies the action. It doesn't explicitly distinguish itself from sibling tools like smi_add_subject_employee_url or smi_add_subject_relationship_url, but the resource and parameter schema make the core purpose clear.

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

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

The description implies usage context by mentioning 'SMI subject' and the schema notes the subjectId comes from a prior smi_get_subject or subject-enrichment call. However, it doesn't explicitly state when to use this tool versus the sibling URL-adding tools (e.g., smi_add_subject_employee_url, smi_add_subject_relationship_url), leaving the agent to infer the distinction.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds meaningful behavioral detail: 'Runs entirely locally; makes no network calls' is a privacy-relevant guarantee. It also qualifies the prefill as 'best-effort,' which manages agent expectations about reliability without contradicting any annotation.

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

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

The description is dense but every clause earns its place: core action, full output contract, downstream usage, and a key execution guarantee. The main action is front-loaded, and the local-execution caveat is placed at the end without burying the primary purpose.

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

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

Given the rich input schema, output schema, and annotations, the description covers everything an agent needs to choose and invoke the tool correctly. It explains what the tool scores, what it returns, how it relates to smi_create_deep_report, and the critical local-execution property. No essential context is missing.

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

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

The input schema already provides 100% parameter coverage, including descriptions for notes, weights, and thresholds. The description adds context by naming the 5 signals and connecting the output to smi_create_deep_report, but it does not add parameter-level semantics beyond schema. Baseline 3 is appropriate.

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

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

The description opens with a specific action ('Scores free-text case notes') and a precise resource, then spells out the full set of outputs: a RECOMMEND/REVIEW/NO ACTION verdict, confidence rating, detected signals, suggested product, and orderData prefill. It also names its downstream sibling (smi_create_deep_report), making it clearly distinct from the many other smi_ tools.

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

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

The description clearly implies this tool is a pre-analysis step that feeds smi_create_deep_report, and 'runs entirely locally' signals a safe, offline analysis stage. It does not explicitly state when to prefer this over alternatives or provide exclusions, so it stops one step short of full guidance.

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

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

Annotations already mark the call as safe read/idempotent, and the description adds valuable behavior beyond them: the state machine, the terminal flag, the guarantee that failed never becomes ready, and the draft non-progression rule. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it defines the result, the polling loop, the stopping conditions, and the sibling actions. The core purpose is front-loaded and no filler is present.

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

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

For a status/polling tool with two fully described parameters and an output schema, the description includes all operational context an agent needs: valid states, terminal semantics, draft handling, and the related submit tools. Nothing important appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining where orderId comes from (draftIds), that there is no separate order-level id, and how product-prefixed ids are normalized. This materially helps an agent construct the parameter correctly.

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

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

Description uses a specific verb ('checks the status') and names the exact resources ('deep report or export record') plus the id source ('smi_create_deep_report draftIds'), which differentiates it from fetch or smi_get_deep_report. The scope is unambiguous and not a restatement of the title.

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

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

It gives an explicit polling protocol: poll while in_progress with bounded attempts/backoff, stop when terminal is true, and stop on draft because it will not progress. It also names the alternatives to call for draft records (smi_submit_deep_reports / smi_submit_exports), so an agent knows exactly when this tool is and is not useful.

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

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

Annotations already indicate a non-read-only, non-destructive operation. The description adds meaningful behavioral context beyond annotations by revealing that it 'persists the deep report upload record' and by requiring the x-amz-version-id header from the PUT, which is critical for correct invocation. It does not discuss failure modes or side effects, but the added persistence detail is substantive.

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

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

The description is two sentences with no filler. The core action is front-loaded, and the parenthetical about the version source is necessary to disambiguate the parameter and is placed efficiently at the end.

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 an output schema exists, the description need not detail return values. It covers the essential workflow context (confirmation after a PUT, specific version requirement, persistence effect). It does not mention error handling or additional prerequisites, but these are largely inferable from the workflow and the provided annotations.

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

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

The input schema has 0% description coverage, so the description must compensate. It explains the 'version' parameter precisely as the x-amz-version-id response header captured during the PUT. The other two parameters, deepReportId and fileName, are not explicitly described but are inferable from the tool's context; the description does not fully compensate for the schema's lack of 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 states a specific verb ('Confirms'), a specific resource ('a file already PUT to a presigned URL returned by smi_request_upload_url'), and the side effect ('persists the deep report upload record'). It clearly distinguishes this tool from siblings like smi_request_upload_url and smi_submit_deep_reports by anchoring it as the post-PUT confirmation step.

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

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

The description provides clear context: it should be used after a file has been PUT to a presigned URL obtained from smi_request_upload_url, and it requires the version header captured during that PUT. However, it does not explicitly state when not to use this tool or name alternatives, so it falls short of full exclusion guidance.

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

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

Annotations already cover readOnly=false, idempotent=false, and destructive=false. The description adds useful behavior: it creates drafts (not final reports), returns IDs for review, and groups all orders under a single project. This goes beyond the annotations without contradicting them.

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

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

Three tight sentences, each earning its place: the action, the output/usage intent, and the critical single-project constraint. The most important 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?

Given the large schema and existing output schema, the description covers the key operational points: draft creation, review-before-submission, and per-project grouping. It misses nothing essential for an agent to call the tool correctly, though it could optionally mention the review path via smi_get_deep_report.

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 only 50%: projectId is well described in the schema, but the required orders parameter has no schema-level description. The tool description only says 'subject orders', providing minimal semantics for a complex array parameter. With half of parameters undocumented, the description should compensate more than it does.

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

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

The description states a specific action ('Creates one or more SMI deep report drafts from subject orders'), identifies the resource (deep report drafts), and clarifies the output ('Returns the draft ids for review before submission'). This clearly distinguishes it from siblings like smi_submit_deep_reports (submission) and smi_get_deep_report (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 gives clear usage context: create drafts first, review their IDs before submission, and group all orders under one project per call ('call once per project'). It does not explicitly name alternative tools or state when not to use it, but the draft-before-submission workflow is clearly implied.

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

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

With readOnlyHint=false and idempotentHint=false already flagging side effects, the description adds that the operation only creates drafts and returns IDs, rather than finalizing them, and that all orders are grouped under one project. This meaningfully shapes an agent's expectations beyond the annotations.

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

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

Three short sentences, all substantive, with the key scoping rule ('call once per project') clearly stated. No filler or repetition.

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

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

For a create-draft tool with an output schema available, the description covers the essential workflow (draft creation, ID return, submission gating) and the main constraint (single project per call). It doesn't enumerate optional order fields, but those are documented in the schema, so nothing critical is missing.

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

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

The schema already documents projectId well and covers roughly half of the order fields with rich descriptions (dates, recipients, reportIdentifier). The description adds only the 'profile-url orders' requirement and the single-project constraint, but does not compensate for the undocumented top-level orders property or optional fields.

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

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

Opens with the specific action 'Creates one or more SMI export drafts' and identifies the input source ('profile-url orders') and outcome ('Returns the draft ids'). This clearly distinguishes it from sibling list/get/submit export tools.

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

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

The description gives concrete usage context: it is the draft-creation step, for review before submission, and mandates one call per project so no call spans projects. It does not explicitly name the submit alternative (smi_submit_exports) or exclusion cases, but the workflow context is clear enough for an agent to select it.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context beyond the schema: it runs locally, makes no network calls, and takes no case data, and it describes the return format as copy-paste-ready Markdown. No contradiction with annotations.

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

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

The description is a single dense sentence with no filler; every clause adds value (return content, routing purpose, client locations, execution properties). It front-loads the core result ('Returns... Markdown system prompt') and keeps supporting details compact.

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

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

For a zero-parameter, no-input-schema, no-output-schema tool, the description is fully complete: it explains what the tool returns, why it exists, where it applies, and its execution characteristics. Nothing an agent needs to correctly invoke it is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description adds useful semantic clarification by explicitly stating the tool takes no case data and runs locally, which prevents an agent from expecting arguments or side effects.

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

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

The description states a specific verb ('Returns') and a precise resource: a consolidated, copy-paste-ready Markdown system prompt with SMI Aware rules, a routing guide, and client-specific paste-in locations. It clearly sets this apart from the many smi_* data-manipulation siblings by framing it as the meta-instruction tool.

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

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

The description conveys clear context: this is for setup/instructions so the assistant calls the right smi_* tools automatically, and it explicitly notes it runs locally with no case data. It does not explicitly name alternatives or say when not to use it, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds genuinely non-obvious behavioral context: SMI accepts the 'findings' include but never populates it, and the response omits the findings key entirely even when findings exist. It also discloses that id prefixes are stripped before the call. No contradiction with annotations.

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

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

Two sentences with everything front-loaded: core purpose first, then routing guidance. Every clause earns its place—'Fetches...', 'Research Bundles are...', 'use this tool...', 'EX ids belong to export tools'—with zero filler.

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, two-parameter tool with an output schema and safety annotations, the description covers all necessary context: id format variants, routing rules, the findings quirk, and the correct sibling for findings retrieval. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, with detailed descriptions for both `id` (prefix meaning, routing) and `include` (accepted values, findings quirk). The tool description reinforces routing but adds no new parameter-level meaning beyond what the schema already states, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Fetches a single SMI deep report by id.' It further distinguishes this tool from the generic fetch tool by noting that Research Bundle ids also route here, and explicitly excludes EX ids as belonging to export tools, making sibling differentiation clear.

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

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

It gives explicit, actionable guidance: use this tool for Research Bundle ids instead of constructing a research_bundle reference for the generic fetch tool, and EX ids belong to export tools. It also points to smi_get_report_findings as the correct alternative when findings are needed, leaving no ambiguity.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to restate those. The description adds useful behavioral context: pagination, downloadable deliverable files (PDF, CSV, JSON), and the conditionally available findings screenshot archive.

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-organized sentence that front-loads the core behavior, then adds release contents and a usage note. There is no filler or repetition of schema/annotation information.

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

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

For a 3-parameter read-only tool with a full output schema and strong annotations, the description covers resource identity, pagination, release contents, and why to call it. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100% for page, take, and deepReportId, so the schema already documents parameter meaning and constraints. The description only reinforces 'pagination' and the deep-report relationship without adding new parameter-level details, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Lists') and a precise resource ('releases for a given SMI deep report'), and it adds what each release contains. The deep-report qualifier distinguishes this tool from the export-release and other deep-report sibling tools without needing to open the schema.

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

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

It provides a clear concrete use case: 'use this tool to fetch the generated report PDF.' The deep-report qualifier also implies this is the correct tool for deep-report releases rather than export releases, though it does not explicitly list when-not-to-use alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds context about id prefix resolution, but doesn't describe behavior like pagination, error conditions, or return structure. Given the annotations cover the safety profile, a 3 is appropriate.

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, front-loaded with the core action and id requirement, followed by a direct routing rule. No wasted words; every sentence earns its place. This is concise 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?

Given that an output schema exists and annotations fully disclose safety, the description covers the essential context for correct invocation. It misses potential error conditions or what constitutes an 'export', but the combination of schema and annotations is sufficient for an agent to call it correctly.

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

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

The schema coverage is 100%, meaning the schema already describes both parameters in detail, including the prefix resolution and the 'include' enum. The description primarily restates the id prefix logic without adding new meaning not already in the schema. Baseline 3 is correct 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 states 'Fetches a single SMI export by id', clearly identifying the verb (fetches), resource (SMI export), and identifier (id). It mentions product-prefixed ids and differentiates from smi_get_deep_report, but overall clarity is strong. Scoring 4 because it is clear but not fully comprehensive about what an 'export' is.

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

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

The description explicitly says 'EX-30001 resolves here, while RB and DR ids belong to smi_get_deep_report', giving direct guidance on when to use this tool vs the sibling. It stops short of explaining when not to use it beyond the id prefix, and the parameter schema also clarifies routing, but no alternative scenarios for the 'include' parameter 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds 'pagination' but this is also present in the schema, and it does not describe output format, ordering, or other behavioral details.

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

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

A single, front-loaded sentence states the action, resource, and pagination with no filler. Every word contributes to understanding.

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

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

For a simple read-only list operation with an output schema and strong annotations, the description is mostly sufficient. It lacks guidance on when to choose this over sibling release tools, but that is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no additional semantic meaning beyond reinforcing that releases belong to an export and are paginated.

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

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

The description uses a specific verb ('Lists') and resource ('releases for a given SMI export'), and mentions pagination. It is clear but does not explicitly differentiate itself from sibling tools like smi_get_deep_report_releases.

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

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

No guidance is given on when to use this tool versus alternatives such as smi_list_exports or smi_get_deep_report_releases. The intended context is only implied by the description.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: findings are grouped by report, ordered by sequence, and pagination is not guaranteed to start at Finding #1 on page 1. This is exactly the kind of non-obvious behavior an agent needs to interpret results correctly.

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

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

The description is dense but every sentence carries information: resource, filters, identifier formats, return contents, ordering semantics, and a pagination caveat. It is front-loaded with the core purpose and avoids filler.

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

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

The description covers the essential call context, including the ambiguity around page ordering and the fact that finding IDs are internal-only. An output schema exists, so the description is not required to detail return fields, and it provides enough operational grounding for correct invocation.

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

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

Schema coverage is 100%, and the schema already documents the accepted ID formats (prefixed or numeric), case-insensitive platform names, and defaults. The description largely restates these details rather than adding new parameter meaning, though it does reinforce the distinction between sequence numbers and internal finding IDs.

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

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

The description uses a specific verb and resource ('Lists SMI release findings') and immediately clarifies scope with pagination and filtering. The resource is distinct from sibling tools like smi_get_deep_report and smi_list_exports, so an agent can identify what this tool returns.

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

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

The description gives clear context for when to use the tool: listing findings with optional report/platform/confirmation/scope filters. It does not explicitly name alternatives or state when not to use it, but the use case is concrete enough for an agent to infer applicability.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by disclosing the return format (structured JSON) and providing a concrete extraction example (subject.birthDate), plus clarifying the input anomaly. No contradiction with annotations.

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

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

Two sentences, no wasted words. The purpose is front-loaded, followed by the key input clarification and a useful return-format example. Well structured for quick agent parsing.

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 single parameter, high schema coverage, and existing output schema, the description covers all essentials: what it does, why the parameter is structured as it is, and what the return looks like. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% – the schema already documents deepReportId and repeats the note about no standalone GET. The description does not add new parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Reads a subject's full profile out of a deep report' with a specific verb and resource. It distinguishes from sibling tools by clarifying the input is deepReportId, not a subject id, and implicitly separates from smi_get_deep_report (report-level read) and smi_update_subject (write).

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

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

The description explains why deepReportId is used (no standalone GET /subjects/{id}), which is useful context, but it does not explicitly name alternatives or state when NOT to use this tool. The intended use case is implied (need subject profile from a deep report) but not contrasted with siblings like smi_get_deep_report.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description needs less safety disclosure. It adds only generic pagination/filtering context and does not surface notable quirks such as the 'findings' include behavior, which is left to the schema. No contradiction exists.

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

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

The description is one tight sentence with zero filler. It front-loads the core operation, then attaches the two key modifiers (pagination, filtering) without redundancy.

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

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

With a rich input schema, annotations covering safety, and an output schema present, the description does not need to explain return values or parameter details. It gives sufficient list-operation semantics, though it could add a one-line pointer contrasting it with smi_get_deep_report for singular retrieval.

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

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

Schema description coverage is 100%: all nine parameters have their own meaningful descriptions. The tool description adds no parameter-level detail beyond the generic phrase 'optional filtering,' so the baseline of 3 applies.

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

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

The description uses a specific verb ('Lists') and resource ('SMI deep reports'), and immediately signals the operation's scope with 'pagination and optional filtering.' This clearly separates the tool from siblings like smi_get_deep_report, smi_create_deep_report, and smi_list_exports.

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 only implies usage through the verb 'Lists'; it does not explicitly say when to choose this tool over smi_get_deep_report or smi_list_exports. An agent can infer the basic use case but receives no guidance about exclusions or alternatives.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context by indicating that the tool returns a paginated list and supports optional filtering, which is useful beyond the annotations.

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

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

The description is a single focused sentence that front-loads the core operation ('Lists SMI exports') before mentioning pagination and filtering. There is no redundant or irrelevant content.

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

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

Given the rich schema with 100% parameter coverage, a true output schema, and four annotations, the description is largely sufficient for an agent to invoke the tool correctly. It could mention ordering or relationship to smi_get_export, but those are not critical 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 all parameters are documented in the schema. The description only generically mentions 'pagination and optional filtering' and does not add specific parameter-level meaning beyond what the schema already provides, which matches the baseline of 3.

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

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

The description uses a specific verb and resource: 'Lists SMI exports' with pagination and optional filtering. This clearly communicates the tool is a read-only collection operation rather than a create or single-get tool, though it does not explicitly name or differentiate sibling tools.

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

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

The usage context is implied by the verb 'Lists' and the mention of pagination/filtering, but there is no explicit guidance about when to use this tool versus siblings like smi_get_export or smi_create_export. No alternatives or exclusions 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond 'lists' the reference set, but it doesn't contradict annotations. It doesn't disclose pagination behavior or return format, but the output schema and parameter defaults cover some of that.

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, concise sentence that front-loads the action and resource. Every word earns its place, and there is no redundant information.

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

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

For a simple list operation with read-only annotations, a full output schema, and fully documented parameters, the description is nearly complete. It could add a note about pagination or the meaning of 'reference set', but the schema and annotations already provide sufficient context for an agent to call it correctly.

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

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

Schema description coverage is 100%, so both parameters (page, take) are fully documented in the schema. The description adds no additional parameter meaning, but the baseline of 3 applies because the schema carries the full burden.

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

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

The description states a specific verb ('Lists') and resource ('SMI reference set of platforms'), which clearly identifies the tool's function. It doesn't explicitly distinguish it from sibling tools like smi_list_products or smi_list_projects, but the resource name 'platforms' is specific enough to avoid confusion.

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 naming the resource, but it doesn't provide explicit guidance on when to use this tool versus alternatives. There are no exclusions or alternative tool references, though the 'SMI reference set' phrasing hints at a canonical data source.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only minor context by calling the data a 'reference set' but does not explain pagination behavior, ordering, or what the returned list represents. The description is consistent with the annotations.

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

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

The description is a single short, front-loaded sentence with no filler or repetition of the tool title. Every word contributes to identifying the operation and the resource.

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

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

For a simple paginated list tool with full parameter documentation, safety annotations, and an output schema, the description is largely sufficient for safe invocation. It falls slightly short because it does not explain what 'products' or 'reference set' means in the SMI domain or how to choose among sibling list tools.

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?

Both parameters, page and take, are fully documented in the schema with defaults, bounds, and descriptions, so the description adds no parameter-level value. With 100% schema description coverage, the baseline of 3 is appropriate.

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

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

The description uses the verb 'Lists' and identifies a clear resource, 'the SMI reference set of products,' so an agent knows what operation and object are involved. It is more specific than the title alone, though it does not explicitly differentiate itself from the many sibling smi_list_* tools beyond the resource name.

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

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

There is no guidance about when to use this tool instead of the sibling list/analysis tools, and no mention of when not to use it. The only usage signal is implied: use it when the SMI product reference list is needed. This leaves tool-selection reasoning mostly to the agent.

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

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

Annotations already establish this as a read-only, idempotent, non-destructive operation. The description adds the pagination behavior beyond the annotations, which is useful context for an agent deciding how to page through results.

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

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

A single sentence conveys the core function and key behavior with no filler. The description is front-loaded with the action and resource, making it easy for an agent to parse quickly.

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

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

For a simple paginated list tool with a rich output schema and strong safety annotations, this description is nearly complete. It does not mention ordering or filtering, but those are not required for knowing how to call the tool correctly.

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

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

Schema description coverage is 100%, so both 'page' and 'take' are fully documented in the schema. The description adds only the general 'pagination' concept, which does not meaningfully improve parameter understanding beyond the schema.

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

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

The description states a specific verb ('Lists') and resource ('SMI projects'), and adds the pagination behavior. It distinguishes itself from sibling list tools by naming the 'projects' resource, though it does not explicitly contrast with those alternatives.

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 this is the tool to use for listing SMI projects, and the sibling set shows separate list tools for other resources. However, it provides no explicit guidance on when to choose this tool over alternatives or when it would not be appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds minimal behavioral context beyond calling the data a 'reference set'; it does not describe ordering, pagination behavior, or response shape, but annotations carry most of the burden.

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 clear sentence with no filler or redundant wording. It is appropriately sized for a simple paginated list operation.

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 straightforward read-only list tool with rich annotations, two documented pagination parameters, and an output schema, the description is mostly sufficient. It could be improved by explaining what an 'SMI relationship' represents or by explicitly noting that this returns reference data, but no critical invocation details are missing.

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

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

The input schema fully documents both parameters with defaults, ranges, and descriptions, so schema coverage is 100%. The description adds no extra parameter meaning, which matches the baseline expectation for fully documented parameters.

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

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

The description states a clear verb and resource: 'Lists the SMI reference set of relationships.' The qualifying phrase 'reference set' somewhat distinguishes this from sibling relationship-related tools like smi_add_subject_relationship, though it does not explicitly name that distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this lists reference/master relationship types, nor does it suggest using it before adding a subject relationship. An agent must infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only that it returns a 'reference set,' but it does not disclose pagination behavior, possible empty results, or any relationship to other SMI objects. This is acceptable but not rich.

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 front-loaded sentence with no redundancy. Every word contributes to identifying the operation and resource, making it appropriately concise.

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

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

Given the simple list operation, complete annotations, fully described pagination parameters, and an output schema, the description provides enough core information for an agent to invoke the tool. It lacks only broader usage context, but nothing critical is missing for a basic reference-data listing.

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

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

The input schema has 100% description coverage for its two parameters, which already clearly document page and take with defaults. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description states a clear verb ('Lists') and a specific resource ('the SMI reference set of statuses'), going beyond the title to indicate this is a reference data lookup. It distinguishes itself from sibling list tools by naming 'statuses', though it does not explain what a status represents.

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?

There is no guidance about when to use this tool versus alternatives like smi_list_platforms, smi_list_products, or other smi_list_* tools. The intended context is only implied by the resource name; no exclusions or alternative selection hints are provided.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds valuable behavioral context: the server never proxies file bytes, the caller must perform the PUT, and the version header must be captured. This goes beyond annotations and clarifies the non-idempotent, state-changing nature of the operation.

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

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

The description is two sentences, front-loaded with the core purpose and file types, then the critical workflow steps. Every sentence earns its place with no redundancy.

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

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

The description covers the essential workflow, file types, and the required follow-up call. It doesn't describe the output schema (though one exists) or potential error cases, but for a tool with an output schema and clear workflow, this is largely complete. The only minor gap is not explaining what the response contains beyond the signedUrl.

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 0%, so the description must compensate. It mentions deepReportId and fileName implicitly by describing the upload context, but doesn't explain the format or constraints of these parameters beyond what the schema provides. The description adds some context (file types) but not detailed parameter semantics.

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

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

The description clearly states the tool requests a presigned URL for uploading a large deep-report reference file, lists supported file types, and distinguishes it from a direct upload by explaining the server never proxies file bytes. This is a specific verb+resource with clear scope.

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

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

The description explicitly explains the workflow: caller must PUT to the returned signedUrl, capture the x-amz-version-id header, then call smi_confirm_upload. It also names the sibling tool (smi_confirm_upload) and the condition for using it, providing clear when-to-use guidance.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation. The description adds that only drafts are accepted and that submission is 'for processing', implying a state transition, but it does not disclose reversibility, side effects, or what happens after submission.

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?

A single, well-structured sentence that front-loads the action and the key constraint. No redundant information or filler; every word contributes to understanding.

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 output schema exists and the single parameter is inferable from context, the description is adequate for a straightforward submit action. It covers the essential prerequisite (drafts exist and are in Draft status) and is not missing critical information for correct invocation.

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

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

The schema defines 'ids' as an array of up to 100 identifiers, but with 0% schema description coverage, the description must clarify the meaning. The phrase 'previously created SMI deep report drafts' implies ids are the draft IDs, but it is not explicitly stated, leaving some ambiguity.

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 'submits' and the resource 'previously created SMI deep report drafts', with an explicit status constraint ('Draft status only'). This distinguishes it from sibling tools like smi_create_deep_report (creation) and smi_list_deep_reports (listing).

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 the tool is for drafts that were previously created, which guides when to use it (after creation, before processing). It does not explicitly contrast with other submit tools like smi_submit_exports, but the resource-specific naming and context make the intended usage clear.

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

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

Annotations already indicate a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds the important constraint that only Draft status items are accepted, which is beyond annotations. However, it does not disclose potential side effects like asynchronous processing or failure modes, so the added value is moderate.

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, front-loaded sentence with no waste. It efficiently conveys the action, target, and constraint without redundancy.

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

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

For a simple submission tool with one parameter and an output schema, the description covers the essential points: what it submits and the status requirement. It does not mention success/failure behavior, but the presence of an output schema may cover that. Overall, it is adequate for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It implies that 'ids' are the identifiers of the previously created SMI export drafts, but does not explicitly state that. For a single parameter, this is sufficient context, though it could be more explicit about the type and purpose of ids.

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 'submits', the resource 'SMI export drafts', and the condition 'Draft status only'. It distinguishes from sibling tools like smi_create_export (which creates) and smi_get_export (which retrieves) without ambiguity.

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

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

The description implies usage context by specifying 'previously created' and 'Draft status only', which tells the agent this is for drafts that exist and are not yet submitted. It does not explicitly name alternatives, but the sibling list provides those and the condition is clear enough.

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

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

Annotations already convey idempotence and non-destructiveness. The description adds genuine behavioral detail beyond them: the SMI backend requires type as a discriminator even when unchanged, and a PATCH with no editable fields is invalid. This helps the agent avoid a likely failure mode.

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

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

Three sentences, all necessary, with the endpoint and most important constraint front-loaded. No filler or repetition of the schema's detailed parameter descriptions.

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 rich input schema, the output schema, and the annotations, the description covers the essential behavioral rules: partial-patch semantics, required type discriminator, editable fields, and the at-least-one-field requirement. Nothing critical is missing for calling this tool correctly.

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

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

Schema coverage is 100% and each parameter is already well described, so the baseline is 3. The description adds value by introducing the cross-field constraint that at least one editable field must be supplied, which is not encoded in the schema's required list. It also groups the editable fields into an API-contract summary.

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

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

The description states the specific verb ('Partially updates'), the resource ('SMI subject'), and the exact endpoint ('PATCH /subjects/:id'). It clearly distinguishes this from sibling tools like smi_get_subject and the smi_add_* family by making the update semantics explicit.

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

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

The description gives clear operational context: type is required on every call, editable fields are enumerated, and at least one editable field must be provided. It does not explicitly name sibling alternatives or exclusion criteria, but the update-versus-add/get distinction is strongly implied.

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

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

Annotations already indicate it is a non-readonly, non-idempotent write operation. The description adds the prerequisite about no existing SMI token and the follow-up behavior, but does not disclose side effects such as duplicate submissions or what response to expect. With annotations covering the core behavioral profile, this is adequate but not rich.

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 tight sentences, front-loaded with the action and resource, followed by the qualifying condition. Every word earns its place; no repetition or filler.

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

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

For a simple four-parameter submission tool, the description covers what, why, and when. It lacks information about the response or error conditions, but with no output schema and straightforward fields, the definition is otherwise complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100% and each parameter has a description. The description merely lists the four fields without adding format, constraints, or relationships beyond what the schema already states. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description uses a specific verb ('Submits'), names the resource ('prospect contact request'), identifies the recipient ('to SMI'), and explains the purpose ('so the sales team can follow up'). It also gives the key fields involved and the target audience, making it easily distinguishable from the many smi_* subject/export/report siblings.

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

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

The description explicitly conditions usage on 'prospects who do not yet have an SMI Aware token,' which is a clear when-to-use/when-not-to-use signal. However, it does not name an alternative tool or say what to use if the prospect already has a token, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is well covered. The description adds value beyond the annotations by naming the SMI identity endpoint and explaining that the resolved account identity is the return payload. It could mention invalid-token behavior, but this is a minor gap for a zero-parameter verification call.

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 sentence that front-loads the action, names the target system, and states the result. There is no redundant or filler wording.

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 no-parameter, read-only, idempotent verification tool with no output schema, the description is nearly complete: it states what is verified, where verification happens, and what is returned. The only notable omission is the exact structure of the resolved identity or failure behavior, but the annotations and simplicity of the call reduce the impact of that gap.

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

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

The tool has zero parameters)Skip and schema description coverage is trivially 100%, so there is no burden on the description to document parameters. Baseline for a zero-parameter tool is 4, and the description appropriately focuses on behavior rather than parameters.

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

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

The description specifies the exact action ('verifies'), the resource ('session Personal Access Token'), the endpoint ('SMI identity endpoint'), and the expected outcome ('returns the resolved account identity'). It is clearly distinct from the sibling smi_* tools, which handle exports, reports, subjects, and uploads rather than access verification.

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 when to use the tool—whenever an agent needs to verify the current session PAT or resolve the account identity—but it does not explicitly state when not to use it or name any alternative. There is no direct sibling alternative, so the implied usage is clear enough, but explicit routing guidance is missing.

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