AALY

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

Goes well beyond the annotations. Annotations only say non-readOnly/non-idempotent/non-destructive; the description explains that the record is metadata-only, that method is configuration not execution, that public routes have no caller identity and typically run as a full-privilege service account via a stored key, and that there is no per-endpoint permission scoping. These are exactly the behavioral risks an agent needs.

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

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

Front-loaded with the write-only/definition-only distinction, then structured into 'What it defines', 'auth', and 'No nested paths' sections. A few clauses are dense and reference sibling tools, but nothing is filler; the length is justified by the behavioral risks it must convey.

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

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

For an 8-param, non-idempotent create with no output schema, the description covers what the record is, how it is wired to functions, auth implications, request-validation technique, and path-shape constraints. An agent has everything needed to call it correctly and safely.

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 high (88%) and every parameter already has a description, so the schema carries the semantics. The description adds real value for auth and method (explaining they are config, not actions) and for function-attachment wiring, but the remaining parameters (label, project_id, description) get no added meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('creates one route DEFINITION record in the project's schema') and immediately distinguishes what it is NOT ('does NOT call any API, send any HTTP request, or read or write application data'). This disambiguates it from runtime/call siblings and from create_function, which a naive reader might confuse with route definition.

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

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

Gives explicit routing: use list_endpoints to read routes back, use create_function with trigger_point='endpoint' to attach execution, use create_field for request validation, and read the aaly://platform/functions resource before the first function. It also names the auth mode tradeoffs ('required' vs 'public') so the agent knows which to pick when.

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=false / destructive=false / idempotent=false, so the safety bar is lower. The description still adds real behavior beyond them: CRUD endpoints activate immediately upon creation (a live side effect), and the key is a unique 3-char UPPERCASE constraint. It does not mention duplicate-key errors or naming collisions, so not full marks.

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, front-loaded with the action, then the side effect, then the field-bulk tip. Nothing is wasted, though the key-format sentence duplicates the schema param description rather than adding new 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 an 8-parameter creation tool with no output schema, the description covers purpose, side effect, and the highest-leverage parameter (fields). Undescribed in the prose are `methods`, project_id fallback, and the returned shape, but those are documented in the schema. Adequate overall, with modest 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 coverage is 100%, so the baseline is 3. The description genuinely adds meaning on the `fields` argument by framing it as a single bulk request that replaces N create_field calls, and pins the key format constraint. The key restatement is redundant with the schema, hence 4 rather than 5.

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

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

States a specific verb + resource + scope: 'Define a new data entity under a project.' It also catches the edge case by pointing at the internal alternative ('instead of a create_field per field'), which helps disambiguate from siblings. It does not, however, explicitly contrast with update_entity/delete_entity, so the sibling differentiation is partial.

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

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

Gives a clear situation for use (defining a new entity) and explicitly names a routing decision: use the bulk `fields` argument rather than calling create_field repeatedly. There are no explicit 'when not to use' exclusions (e.g. use update_entity to modify an existing one), so it stops short of a 5.

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

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

Annotations provide only basic hints, but the description discloses crucial behavioral traits: type/cardinality/targets are permanent once set, stored=false cannot combine with search or unique, and endpoint fields have forced/rejected settings. It also explains that stored=false fields only get values via platform hooks, which is vital context beyond the annotations.

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

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

The description is very long and dense, though it uses all-caps headers to organize sections. It front-loads the core purpose, but many sentences are verbose and could be trimmed without losing meaning.

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

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

Given 21 parameters, nested objects, and no output schema, the description covers most necessary context: type selection, endpoint usage, and permanence. It omits any reference to the create_fields sibling, which could be an alternative for adding multiple fields.

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

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

Schema description coverage is 95%, so the schema already documents most parameters. The description adds cross-parameter guidance (e.g., use 'reference' with multiple:true for arrays of links) and permanence warnings that complement the schema, though it largely reinforces existing schema details.

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

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

The description states a specific verb and resource: 'Add a new field to an entity schema.' It distinguishes from siblings by naming update_field for later changes and describing how it applies to the built-in users entity, making the tool's scope 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 gives extensive guidance on when to use each type (reference vs list, enum, computed/stored) and explicitly warns against storing relationships as text or list. However, it does not mention the sibling tool create_fields, leaving an alternative for bulk creation unaddressed.

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

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

Goes well beyond the annotations (non-destructive, non-idempotent) by disclosing that partial success is normal, the exact result shape (`summary` plus per-field `_ref`/`status`/`body`), that failures are isolated, and that `status: null` with NOT_ATTEMPTED means a deadline hit and the item should be resubmitted as-is. This is precisely the retry/mutation semantics an agent needs for a non-idempotent bulk write.

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?

Front-loaded with the bulk purpose and the alternative, and the caps-labeled sections (PARTIAL SUCCESS IS NORMAL) make it scannable. It is dense and long, but nearly every sentence carries distinct, non-redundant information about the result contract.

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?

There is no output schema, so the description carries the full burden of explaining the return value — and it does, documenting `summary` counts, per-field entries, error `body` shape, and the NOT_ATTEMPTED case. Nothing needed to call or recover from this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by enumerating the accepted item attributes and pointing to create_field as the authoritative source for type/cardinality/immutability guidance, plus the entity_id-is-EPT case. It stops short of adding meaning the schema lacks, but the cross-reference is genuinely useful.

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

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

States a specific verb+resource with explicit scope: 'Add MANY fields to one entity in a single call — one bulk POST /fields instead of one create_field per field.' An agent can immediately distinguish it from the sibling create_field.

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

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

Explicit routing: 'read create_field's description first' for per-field semantics, and 'Prefer this over repeated create_field calls whenever you are defining two or more fields on the same entity.' The when-to-use condition and the alternative are both named.

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

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

Adds substantial context beyond the annotations: metadata-only with no deploy, 30s propagation for edits, whole-chain budgets (2s/5s/30s, note exceeding API Gateway's ~29s), 5-min async budget with failures only in CloudWatch, and lowest-first chaining semantics. This is far richer than the flat readOnly/destructive/idempotent hints.

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?

Front-loads the critical metadata-only distinction and structures the rest by theme (resource pointer, four axes, timing). It is long, but nearly every sentence conveys non-obvious behavior; only the budget aside is somewhat dense, not wasteful.

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 13-parameter, schema-rich tool with no output schema, the description covers behavior, timing, budgets, chaining, cross-tool dependencies (deploy_functions, create_endpoint), and the resource to consult. 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 92%, so the baseline is 3, but the description adds semantic meaning the schema does not: methods is irrelevant for trigger_point 'endpoint', execution_mode is ignored there too and lives on the endpoint, and order controls same-trigger chaining where each Function receives the prior output. These resolve real ambiguity between interdependent 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?

States a specific verb+resource ('Define a Function: customer Python that runs on an entity's request lifecycle') and immediately scopes it as metadata-only, explicitly naming deploy_functions as the thing that does not happen here. An agent can tell it apart from create_endpoint, deploy_functions, and update_function without opening a 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?

Gives strong context: read the aaly://platform/functions resource before the first one, and points to create_endpoint for the endpoint trigger_point. It explains the four decision axes and the timing of metadata vs deploy effects, but stops short of an explicit 'use this instead of X when Y' statement against update_function or the code-deploy sibling.

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 non-readOnly, non-idempotent, non-destructive, closed-world. The description adds genuinely new behavior: the project's DynamoDB table is provisioned asynchronously (~30 seconds) and the id is auto-generated (e.g. 'PRJ3'). It doesn't cover auth requirements or error behavior, but the async provisioning latency is a valuable disclosure 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 tight sentences, front-loaded with the core action and immediately followed by the return value and the async caveat. Every sentence earns its place with no 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?

With no output schema, the description correctly steps in to describe the return (new project record + id format) and the async table provisioning delay. What is missing is auth/permission context and failure behavior for a creation tool, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 100%, so the schema already fully documents name, slug, description, multiTenant, and publicSignup, including dedupe and signup semantics. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new project under the platform customer') and goes further to describe the return value (new project record with auto-generated id) and a downstream dependency (the id feeds create_entity). This clearly distinguishes it from sibling create_* tools like create_entity and create_endpoint.

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

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

Provides clear sequencing context — 'Use this id for create_entity calls' — telling the agent how this tool fits into a workflow. However, it gives no explicit when-to-use/when-not guidance relative to alternatives, and there is no exclusion or prerequisite stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantive behavioral detail beyond them: the deletion is soft, has a 30s propagation window, and leaves attached Functions intact though unreachable. These side-effect and timing disclosures are exactly the kind of context annotations cannot carry.

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

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

Two economical sentences: the mutation type is front-loaded, followed immediately by the operational consequences. Every clause carries information; nothing is filler or repetition of the title.

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 annotations covering the safety profile and no output schema to explain, the description is nearly sufficient — it covers mutability, timing, and collateral effects on Functions. Only the precise handling of a nonexistent or already-deleted endpoint_id is left unaddressed, 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 0% for the single endpoint_id parameter, and the description adds no clarification of it. However, the parameter is a single self-evident identifier whose name and required status leave little ambiguity, so the description does not need to compensate heavily.

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

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

States a specific verb + resource ('Soft-delete a custom endpoint') and qualifies the operation as a soft delete, which separates it cleanly from sibling deleters like delete_function, delete_entity, and delete_field operating on different resources. An agent can identify the target and the mutation type without opening 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?

The description supplies decision-relevant context — routing stops within 30s, attached Functions are untouched but become unreachable — which tells an agent what happens if it proceeds and implicitly signals this is the reversible alternative to a hard removal. It stops short of explicitly naming an alternative (e.g. update_endpoint to merely disable routing) or stating when not to use it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely important context that the annotations cannot express: the deletion is soft and existing data records survive. That clarifies the actual blast radius of a tool flagged 'destructive'. It stops short of saying whether the soft-delete is reversible or how to restore it.

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 short sentences, zero filler, and the most decision-relevant fact (soft-delete, data preserved) is front-loaded. Nothing wastes the agent's attention.

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

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

For a destructive mutation, the annotations carry the safety profile and the description supplies the soft-delete nuance, which is the key missing piece. No output schema exists so return values need not be explained, but reversibility and any post-delete state are still unstated.

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?

Only one parameter (entity_id) and the schema documents it at 100% coverage with an example value ('ENT3'). The description adds no additional parameter semantics, 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?

States a specific verb (soft-delete) and resource (entity schema), and the qualifier 'schema' distinguishes it from sibling mutations like delete_field, delete_endpoint, and delete_function. An agent can identify the target without opening 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?

The description explains the semantic effect of the deletion but gives no when-to-use, when-not-to-use, or prerequisite guidance (e.g., whether the entity must be empty, or when to prefer update_entity). Nothing routes the agent between delete_entity and its siblings.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely new behavior beyond the annotations: the deletion is soft, existing records keep their data, and the field stops participating in validation and responses. That is the key fact an agent cannot get from the structured fields.

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 short sentences, no filler, and the operation and its consequence of record retention are front-loaded in the order an agent needs them.

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 one-parameter, no-output-schema tool, the description plus annotations give an agent nearly everything needed to invoke it correctly. The only omission is whether a soft-deleted field can be restored or how to do so, which would be a useful but not essential addition.

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?

There is a single parameter and the schema description coverage is 100%, including an example ID format ('FLD12'). The description adds nothing about field_id, so the baseline of 3 applies – the schema does all the work here.

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

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

States a specific verb+resource ('Soft-delete a field'), which is unambiguous among siblings like update_field, list_fields and create_field. It does not name a sibling for contrast, but the operation itself is distinct enough that an agent needs no cross-referencing.

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 word 'soft-delete' implicitly tells the agent this is not a hard removal and that the data survives, which is usage-relevant. However, there is no explicit when-to-use guidance, no prerequisites (permissions, live traffic impact), and no mention of any alternative path for permanently removing a field.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantive behavior beyond them: it discloses that this is a soft delete, that the function stops running within 30s, and that the deployed code bundle is preserved. That is exactly the 'what gets destroyed vs. kept' context an agent needs.

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

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

Two tight sentences with the key action front-loaded and the timing/preservation details immediately following. No 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 single-param mutation with annotations covering the safety profile and no output schema, the description supplies the crucial semantics (soft delete, 30s stop, bundle retained). It could note reversibility/restore path, which is the only notable omission.

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

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

Schema coverage is 0% and the single function_id parameter is undocumented in both schema and description. 'a Function' implies which entity is targeted, but no format, source, or retrieval hint is added, so it does not compensate for the coverage gap.

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

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

States a specific verb+resource ('Soft-delete a Function') and the 'soft' qualifier usefully distinguishes it from a hard delete. It does not explicitly contrast with sibling tools like update_function or delete_endpoint, so it stops just 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?

There is no guidance on when to use this versus alternatives such as update_function (which might disable rather than delete) or other delete_* siblings. The reader must infer the usage context entirely.

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

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

Goes beyond annotations by disclosing fallback behavior per channel type (email falls back to platform default; slack/whatsapp stop delivering) and clarifies the secret is NOT deleted. These are non-obvious side effects. However, it doesn't mention permissions or whether deletion is reversible despite destructiveHint.

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: core action, per-channel fallback behavior, and secret-cleanup routing. Front-loaded with the primary purpose.

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

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

For a single-param destructive tool with annotations and no output schema, the description covers the key non-obvious behaviors (fallback semantics, secret independence) and routes to delete_secret. It lacks param format guidance and permission details, but is largely complete.

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

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

Schema description coverage is 0% and the single parameter channel_id has no description. The tool description doesn't explain the parameter's format or how to obtain it. With 1 param and a low-coverage schema, the description should compensate but only marginally does by implying it identifies a channel.

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?

Clear verb+resource: 'Delete a notification channel'. Distinguishable from sibling delete_secret and delete_notification_template, though it doesn't explicitly contrast itself against them. The core purpose is unambiguous.

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

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

The description implies usage (deleting a channel) and cross-references delete_secret for cleaning up the underlying secret, which is helpful guidance. But it doesn't state prerequisites, permissions needed, or when deletion is appropriate versus disabling.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description goes beyond them by explaining what happens to sends that name a deleted template: they fall back to the platform's shipped default if one exists, or fail with TEMPLATE_NOT_FOUND rather than emitting an empty message. That is genuine post-deletion behavior not present in the annotations.

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

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

Two tight sentences with the action front-loaded and the consequence immediately after. The second sentence is slightly garbled ('Sends naming it fall back'), which costs minor readability but not length.

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

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

No output schema exists, and annotations carry the safety profile, so the description only needs to cover the action and its side effects. It explains the deletion consequence and the failure mode, which is enough for a one-parameter destructive tool.

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

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

The single required parameter template_id has 0% schema description coverage, and the description never defines it. It only obliquely implies the template is addressed by a 'key' in the fallback sentence, leaving the agent to infer whether the value is an internal ID or a key string. Adequate but a clear gap for a 0%-coverage required parameter.

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

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

The opening sentence gives a specific verb (Delete) and resource (notification template), which cleanly separates it from delete_notification_channel and set_notification_template. It does not, however, explicitly contrast the delete semantics against its siblings the way a top-tier definition would.

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 statement of when to delete a template versus using set_notification_template to change it, nor any prerequisites or warnings about irreversible removal. The second sentence describes a downstream consequence of deletion but offers no selection 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds a critical behavioral distinction: this is a genuine, immediate, hard deletion rather than a soft delete. This goes beyond the annotations and informs the agent about irreversibility and intent, though permissions or error behavior are not covered.

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

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

Two sentences, front-loaded with the action and followed by a valuable behavioral nuance. No wasted words, and the key differentiator is placed prominently.

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

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

For a simple one-parameter delete tool with no output schema, the description covers purpose and behavioral nuance well, and annotations handle the safety profile. However, the complete absence of parameter semantics (0% schema coverage) is a notable completeness gap that the description does not address.

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

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

The schema description coverage is 0% for the sole parameter secret_id, and the description provides no information about what secret_id represents (e.g., name, ID, format). The parameter name is self-explanatory, but the description fails to compensate for the schema gap, leaving semantics unclear.

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

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

States a specific verb and resource ('Delete a secret') and immediately distinguishes the operation from the platform's soft delete. An agent can tell it apart from sibling delete tools and understand the action without opening 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?

The second sentence implies a use case (a revoked credential must not outlive its revocation) and contrasts with the usual soft delete, giving implicit guidance. However, it does not explicitly state when to use this tool versus alternatives like set_secret, nor does it outline any prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a destructive, idempotent write. The 'non-secret' qualifier adds a useful scope constraint beyond annotations, but the description doesn't note irreversibility, required permissions, or side effects like breaking functions that reference the variable.

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 zero filler. 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?

For a one-parameter destructive tool, the description covers the essentials minimally. Annotations carry safety; the schema covers the parameter; but the description omits when to use it, what happens to dependent functions, and how to obtain variable_id.

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% and there is one parameter. The description adds the 'non-secret' constraint that helps scope which variables qualify, but provides no format, source, or identification guidance for variable_id.

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

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

States a specific verb (delete) and resource (Function variable), and the qualifier 'non-secret' usefully distinguishes it from delete_secret. It doesn't explicitly name that sibling, but the qualifier serves the same differentiating purpose.

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

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

There is no guidance on when to use this tool versus alternatives. The 'non-secret' qualifier implies a boundary with delete_secret, but no explicit condition or alternative is stated.

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

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

Annotations only flag destructive/idempotent/readOnly; the description adds substantial behavior beyond them: async return with status 'deploying', settlement to 'ready'/'failed', verbatim zip layout preservation, and the fact that dependencies must be vendored because the platform will not run pip on customer input.

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?

Four dense sentences, each load-bearing: scope, prerequisite, packaging constraint, async/rollback. Front-loaded with the plural-naming rationale so the agent grasps the project-level model immediately.

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

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

With no output schema, the description compensates by explaining the async lifecycle and how to observe completion, plus dependency vendoring and rollback. Nothing an agent needs to invoke this 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 already 100%, so baseline is 3, but the description adds real meaning: code_file_id must originate from upload_file, and the zip's internal layout determines handler dotted paths (e.g. 'orders.before.validate' needs orders/before.py).

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

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

States a specific verb+resource ('Deploy a project's Function code bundle') and immediately disambiguates scope with 'Project-level, not per-Function', which cleanly separates it from create_function/update_function 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?

Gives an explicit prerequisite ('Upload the zip first with upload_file, then pass the file id here'), names the follow-up tool (list_deployments) and the polling condition, and even covers the rollback path as 'this same call with an earlier file id'.

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, destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing what the response actually contains (multiTenant semantics, entity/field inventory, reference fields, working query filters), which annotations cannot convey. Minor gap: no note on whether the call can be expensive or on auth scoping.

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 tightly packed sentences with no filler; the capability summary comes first and the when-to-use / alternative routing follows. Every clause carries information that helps selection or interpretation.

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?

No output schema exists, but the description enumerates the returned sections (tenant model, entities, relationships, filters), so an agent knows what to expect. Combined with annotations covering the safety profile and a 100%-documented sole parameter, nothing needed 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 coverage is 100% and the single project_id parameter is fully documented in the schema, including the whoami default fallback. The description adds no syntax or format detail beyond the schema, so the baseline 3 for schema-covered parameters 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?

States a specific verb (describe) and resource (project) and then enumerates exactly what the overview contains: tenant/data-sharing model, entities with fields, relationships, and active filter parameters. This is clearly distinguishable from list_entities, list_fields, and generate_openapi_spec, which are named directly.

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

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

Explicitly says when to use it ('before writing app code') and names two alternatives with the condition that selects them: use this instead of piecing data together from list_entities + list_fields, and use generate_openapi_spec for the machine-readable REST contract.

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 the side-effect profile (not read-only, not idempotent, not destructive), so the description need not restate safety. It adds real context beyond that: requests become tracked demand tagged with the build context, and use_case drives prioritization. It stops short of stating auth requirements or that duplicates are merely discouraged, not blocked.

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

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

The core action is front-loaded and the routing guidance follows immediately with zero filler. Two paragraphs are slightly heavier than strictly necessary, but each sentence carries actionable content.

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

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

For a 13-parameter mutation tool with no output schema, the description covers purpose, routing, and the key parameter's role well. It omits auth/prerequisite context and gives no hint of what filing returns (e.g., a request ID to vote on later), 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 coverage is 62%, so the schema documents most fields. The description nonetheless adds meaning the schema lacks — that use_case is the single most useful field for prioritization and should be filled even when brief, and that capability_gap should be tagged for clustering. This goes beyond the schema's field definitions for the highest-value parameter.

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

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

States a specific verb and resource ('Request a capability the AALY platform does not have today') with clear scope. It is immediately distinguishable from siblings like file_support_ticket and vote_feature_request, which serve different intents.

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

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

Explicitly prescribes the workflow: call list_feature_requests FIRST, prefer vote_feature_request over a duplicate, and file here whenever a capabilities guide says something is not implemented. The when-to-use condition and the alternative are both named.

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 the write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), lowering the bar. The description adds genuine behavioral context beyond that: passing request_id lets a human join directly to the request's full trace instead of reproducing blind, revealing human triage happens downstream. It doesn't mention that repeated calls create duplicate tickets (relevant given non-idempotent), so it stops short of a 5.

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

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

Two paragraphs, front-loaded with purpose and the sibling alternative before parameter provenance. The parentheticals are dense but each earns its place, advancing routing and parameter sourcing rather than restating the name.

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

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

For a 17-parameter, non-idempotent mutation tool with no output schema and no annotation title, the description covers routing, the key integration fields, and the human follow-up path. It is nearly complete; it could note duplicate-creation behavior and priority implications but nothing essential to calling 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 71%, so the schema documents most fields; the description adds cross-tool provenance that the schema lacks — request_id comes from the error response or a prior list_logs/get_request_trace call, and attachment_ids accepts file records from upload_file. That materially helps correct invocation, though several params (actual_behavior, steps_to_reproduce, environment, client_name) get no added meaning.

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+resource ('File a bug report, question, incident, or billing/access issue against the AALY platform') and enumerates the ticket kinds. It also names the sibling it is not (file_feature_request) and the retrieval siblings it complements (get_request_trace, list_logs). An agent can distinguish it from siblings without opening a 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 gives explicit when-to-use ('especially when you hit an actual error, not just a documented capability gap') and a clear alternative with its selecting condition ('for a missing capability, use file_feature_request instead'). This is textbook when/when-not/alternative guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the remaining burden is light. The description still adds real value by disclosing the S3 upload side effect, the presigned-URL return, and what the spec contains — behavior an agent cannot infer from 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?

Three sentences, front-loaded with the action and side effect, then the return value, then scope clarification. Every sentence earns its place, though the scope sentence is somewhat lengthy for the marginal point it makes.

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?

There is no output schema, but the description explicitly states what is returned (a presigned URL) and what the artifact contains. Combined with the annotation safety profile and a fully documented single parameter, an agent has everything needed 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%, and the schema already explains the project_id field including the whoami default_project_id fallback. The description adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb (Generate) and resource (OpenAPI 3.0 spec) plus the side effect (upload to S3) and the return (presigned URL). No sibling tool does anything comparable, so it is trivially distinguishable from the create_/list_/update_ family.

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 second sentence clarifies an important boundary — the generated spec describes the project's REST API and 'this MCP does not proxy data CRUD' — which steers agents away from misusing it. It does not, however, state explicitly when in a workflow to call it (e.g. after entities/endpoints are defined) or name an alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuine behavioral value by disclosing the result shape: ordered Function invocations with status, error text, and captured print() output. It stops short of noting retention windows, result size limits, or behavior when the request id is unknown.

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 payload of the response and followed by the decision rule. The em-dash enumeration is dense but each clause earns its place; the only minor cost is a slightly sprawling first sentence.

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

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

With no output schema, the description must carry the return-value burden, and it does — enumerating request-level fields and the per-invocation fields. Combined with annotations covering safety, an agent has enough to call it correctly; only error/not-found and volume behavior are unaddressed.

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 50% — project_id is documented in-schema, but request_id carries no schema description. The description compensates by explaining what a request_id is and where to obtain it (client error, support ticket, list_logs), which is meaning the schema does not supply. project_id's conditional nature is left to 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?

Specific verb+resource+scope: 'Everything about ONE request in a single call' with an explicit enumeration of what is returned (own status/latency/payload plus every triggered Function invocation, in order). It clearly separates itself from list_logs, which is named as a source of the requestId rather than as an equivalent.

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

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

Explicit when-to-use framed as a scenario ('a request failed, was it my code') plus the precondition (pass the requestId you already have) and three concrete sources for that id: a client error, a support ticket, or list_logs. This routes the agent without ambiguity.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-openWorld, so safety is covered. The description adds real value beyond them by disclosing what the response contains — the full comment thread and attachments — which tells the agent the call may be heavier than a plain record fetch.

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; the scope of the returned payload is stated immediately after the lookup verb.

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 single-parameter read with complete annotations and no output schema, the description covers both what it fetches and what comes back (comments, attachments). Nothing critical is missing, though it does not mention error behavior for an invalid id.

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?

Only one parameter (ticket_id) at 0% schema description coverage, but the name is self-explanatory and 'by id' in the description confirms its role. The description adds no format, type, or example detail 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?

Specific verb ('Fetch') plus resource ('one support ticket') plus explicit scope ('by id, including its full comment thread and attachments'). The word 'one' clearly distinguishes it from the sibling list_support_tickets without needing 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?

Usage is only implied: 'one ... by id' suggests a single-record lookup versus list_support_tickets, but no explicit when-to-use or when-not-to-use guidance is given. An agent can infer the routing but must do the work itself.

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 safety is covered. The description adds genuinely new behavior: results are newest-first, the record includes status/failure message/bundle version/deployer/time, and notably that a failed deployment leaves the previously-ready bundle running. That last point is real operational context an agent could not infer.

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 what the tool returns and what it is for. No filler, 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?

With no output schema, the description usefully enumerates returned fields and ordering, which is the right instinct. However, the three input parameters are entirely undocumented at 0% schema coverage, so an agent cannot tell what limit does or how status filtering behaves.

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 carry the burden, and it largely does not. 'For a project' hints at project_id, but limit and the status enum (pending/deploying/ready/failed) are never explained, and the fields listed (bundle version, deployer) are return values, not 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?

States a specific verb and resource ('Deployment history for a project'), plus ordering ('newest first') and the fields returned. It implicitly contrasts with the sibling deploy_functions via the 'did my deploy work' framing, but never names an alternative explicitly, so it falls short of full sibling differentiation.

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

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

The phrase 'did my deploy work' implies the post-deploy verification context, which is useful, but there is no explicit when-to-use guidance, no conditions, and no named alternative (e.g. deploy_functions for triggering a deploy vs. this for checking one). Usage is left 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully carried by structured data. The description's only additional contribution is the 'non-CRUD' scoping, which is more purpose than behavior; it says nothing about pagination defaults or result ordering.

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 with the resource scope front-loaded and the optional filters second. Nothing is wasted and nothing important is buried.

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?

No output schema exists, and the description does not describe the return shape, pagination behavior, or defaults for limit/offset, which matter for a list tool with unbounded results. Adequate but with clear gaps for a 4-parameter listing endpoint.

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 only 25% — entity_id is documented but project_id, limit and offset are not. The description recovers the meaning of project_id and entity_id as filters, but 'limit' and 'offset' remain entirely undefined, so the compensation is partial.

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

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

States a specific verb ('List') plus a precisely scoped resource ('custom, non-CRUD endpoint routes'), which cleanly separates it from CRUD-oriented siblings like update_endpoint/delete_endpoint. It does not explicitly name a sibling alternative, 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 implies usage via 'Optionally filter by project_id or entity_id', giving the agent a sense of how to narrow results, but it offers no when-to-use guidance, no prerequisites, and no alternatives (e.g. get vs list). Implied usage only.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds nothing about pagination defaults, result ordering, or empty-result behavior beyond what the schema states.

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 short sentences, front-loaded with the core action and followed by the optional scoping behavior. No wasted words.

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

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

For a simple read-only list tool with a fully documented schema and no output schema, the description covers the essentials. Minor gaps (pagination semantics are only in the schema) are acceptable given the low complexity and rich annotations.

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

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

Schema description coverage is 100%, so limit, offset, search, and project_id are all documented in the schema. The description restates only the project_id filter and adds no format or behavior detail 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?

States a specific verb and resource ('List entity schemas'), which distinguishes it from siblings like list_projects, list_fields, and list_functions. It does not explicitly name an alternative, but the resource is precise enough to be 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?

The description explains the optional project_id scoping ('to see only entities under a specific project'), which implies when to use it, but offers no explicit when-not guidance or pointer to alternatives such as list_projects for a project-level view. Usage is only 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the deduplication workflow context, but says nothing about pagination, default limit, or result ordering for a tool that exposes a limit parameter.

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 waste: purpose and filter scope are front-loaded, then the usage instruction. Every clause 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 read-only list tool with no output schema and annotations covering safety, the description covers purpose, filter scope, and workflow well. The remaining gap is limit/pagination behavior, which is minor given the tool's simplicity.

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 carry the load, and it names 4 of 6 parameters (status/priority/area/project) as filter dimensions. However, 'limit' and 'blocking' are never mentioned or explained, so the compensation is only partial.

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

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

States a specific verb (List) and resource (feature requests) plus the filterable dimensions (status/priority/area/project), which lets an agent distinguish it from the sibling list_* tools. It also separates itself from file_feature_request and vote_feature_request by naming the workflow it belongs to.

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

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

Explicitly tells the agent when to call this (before file_feature_request, to check for an existing match) and what to do instead when a match is found (vote rather than file a duplicate). This is a named alternative plus the condition that selects it.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered, yet the description adds real value by enumerating what comes back (field names, types, validation rules, enum values, reference targets). It does not mention pagination behavior or result size guarantees, which is the remaining gap.

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

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

Two sentences, zero filler, with the action front-loaded and the return payload described immediately after. Every clause 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 no output schema, the description usefully compensates by describing the returned field metadata, and pagination is covered by the limit/offset schema entries. Only the absence of any guidance on large result sets or default result ordering keeps it from being fully complete.

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

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

Schema description coverage is 100%, so entity_id, limit and offset are all documented in the schema; the description adds only the scoping meaning of entity_id. Baseline 3 is appropriate when the schema carries the parameter detail.

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

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

States a specific verb and resource ('List field definitions') and scopes it to 'a specific entity', which implicitly separates it from list_entities and create_field. It is clear on its own, but it never names a sibling or contrasts scope against them.

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

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

Usage is only implied by the phrase 'for a specific entity' plus the required entity_id – an agent can infer you call it when you have an entity and want its field schema. There is no explicit when-to-use, when-not-to-use, or named alternative among the many list_* and create_field siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the filterable dimensions but says nothing about pagination defaults, result volume, or ordering, which is the remaining behavioral gap. With annotations carrying the main burden, 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?

A single front-loaded sentence that states the action first and the optional narrowing second, with zero filler. Nothing is redundant or buried.

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

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

For a 6-parameter list tool with no output schema and 0% schema description coverage, the description leaves the pagination contract (limit/offset) entirely undocumented and gives no hint of return shape or default page size. It covers the filtering story adequately but not the full calling contract.

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% across 6 parameters, so the description has to compensate. It names four of them (project, entity, trigger point, enabled state) in natural language, but limit and offset are never mentioned and no filter syntax or enum values ('before-request'/'after-request') are clarified.

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

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

States a specific verb ('List') and resource ('Functions') and enumerates the available filter dimensions, so an agent can tell this is the read counterpart to create_function/update_function. It does not explicitly contrast itself with the many sibling list_* tools, but the resource noun is unambiguous.

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

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

The phrase 'optionally filtered by...' implies when the tool is useful (broad listing, narrowed by project/entity/trigger/enabled), which is implied usage rather than explicit guidance. There is no statement of when to prefer a sibling such as describe_project or list_deployments, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description goes further by disclosing that unfiltered unbounded queries are rejected, that `requests` rows never expire, that payloads are redacted, and that function_logs carry full error text and captured print() output. These are behavioral facts not present in the structured data.

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

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

Front-loaded with the purpose and the two modes, then filters and the hard requirement. Every sentence carries information, though the quoted debugging tagline is slightly more rhetorical than functional.

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

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

For an 11-parameter, no-output-schema read tool, the description covers the return shape per log_type, the mandatory-filter contract, and the sibling alternative. Minor gaps (limit semantics, project_id default resolution) remain, but they are covered by schema descriptions.

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

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

With 73% schema coverage the description still adds real meaning: which filters are exact-match and fast, that function_id and status are function_logs-only, and the cross-parameter requirement that one bounded filter must be supplied — a constraint the schema does not express. It does not elaborate on limit or project_id defaults, keeping it short of a 5.

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

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

States a specific verb (browse/list) plus the two distinct resources (request logs and Function execution logs) and frames the exact debugging question it answers. It explicitly separates log_type='requests' from log_type='function_logs' and names get_request_trace as the sibling for single-request lookups, so an agent can distinguish it without opening a 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?

Explains when to pick each log_type, states the mandatory-filter rule ('at least one of those, an exact request_id, or a bounded time range is required'), notes that unfiltered queries are rejected, and routes the agent to get_request_trace when it needs both sides of one request. Nothing is left 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral value beyond that: it explains the return semantics around secrets — only the secret NAME is exposed, never a credential value. That is a meaningful disclosure for an agent reasoning about data exposure, though return shape and pagination remain unspecified.

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, and the second sentence earns its place by clarifying the secret-exposure behavior. No 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 list tool with annotations covering safety and no output schema, the description covers purpose and the key secret-handling nuance. However, with 0% schema coverage it leaves both parameters and any return/pagination detail unexplained, making it minimally adequate rather than complete.

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

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

Schema description coverage is 0% and both parameters (limit, project_id) are undocumented in the schema. The description implies project scoping via 'a project's' but says nothing about the limit parameter or any defaults/pagination behavior, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource scoped to a project ('List a project's notification channels'), which clearly separates it from create/set/delete siblings sharing the notification-channel resource. It does not explicitly distinguish itself from list_notification_templates, but the resource noun is precise.

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 on when to call this versus alternatives such as list_notification_templates or list_secrets, and no mention of prerequisites or required permissions. The agent must infer usage from the 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 establish readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope. The description goes beyond that by disclosing an important result-scope behavior: shipped platform defaults are excluded and apply implicitly when no template matches. This adds real value, though pagination/limit behavior is not addressed.

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, no filler, and the most valuable scoping fact (defaults are excluded) is placed second where it reads as a caveat to the primary statement.

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

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

For a read-only list tool with a rich annotation set and no output schema, the description covers the resource, the returned content (rendered Mustache source), and the fallback behavior. The remaining gap is the filtering/pagination surface (limit, channel_type), which an agent would have to infer.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies the project scope ('a project's notification templates') but says nothing about the limit control or the channel_type enum filter, leaving two of three parameters unexplained anywhere.

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

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

States a specific verb and resource ('List a project's notification templates') and adds the distinguishing content detail that results include the Mustache source. This separates it cleanly from sibling list_notification_channels and the delete/set template 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?

Usage is implicit: the tool is clearly a read operation over a project's templates, and the note about platform defaults hints at when results may be empty. However, it never says when to prefer this over list_notification_channels or how it pairs with set_notification_template, and no prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. With no output schema, the description's enumeration of returned fields (id, slug, name, flags, provisionStatus, _createdAt) is genuine added value, though it says nothing about pagination totals or ordering.

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 short sentences, zero filler, with the purpose front-loaded before the return-value list. The second sentence is a dense enumeration rather than prose, which is efficient for this kind of tool.

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-required-parameter list tool with full schema coverage and read-only annotations, the description covers purpose and return shape, which is what's missing without an output schema. It omits pagination/ordering behavior and total-count semantics, minor gaps for a listing endpoint.

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%, including the notable 'applied client-side' caveat on search, so the description needn't restate parameters. It adds no syntax or interaction detail (e.g., whether search combines with limit/offset), so the baseline 3 is appropriate.

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

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

States a specific verb and resource (list projects) and adds scope ('under the platform customer'), so an agent knows exactly what enumeration this is. It does not explicitly differentiate from nearby siblings such as describe_project or list_endpoints, but the resource noun makes the distinction self-evident.

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 when-to-use, when-not-to-use, or alternative is named. The agent gets no signal about preferring list_projects over describe_project for a single project, or how the client-side search relates to other lookup tools.

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

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

Annotations already declare the safe read-only profile, so the bar is lower, and the description still adds genuinely new context: values are never returned, only a masked preview and fingerprint. That disclosure is exactly the behavioral trait an agent needs and is not covered by 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?

Two sentences, front-loaded with the core action and the critical 'VALUES ARE NEVER RETURNED' constraint. Every clause earns its place by describing the returned data.

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

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

With no output schema, the description carries the return-shape burden and does so well via the masked-preview/fingerprint explanation, while annotations cover safety. The main gap is that pagination (limit) and required-parameter behavior remain unaddressed.

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 0% and neither of the two parameters (limit, project_id) is documented in the schema. The description only weakly implies 'a project's' scoping for project_id and says nothing about limit or pagination semantics, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('List a project's secrets') and immediately qualifies the return content, so the agent knows exactly what this does. It does not name a sibling alternative (e.g. list_variables) to sharpen the boundary, which keeps it 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?

Usage is implied by the resource and the note about confirming a secret still matches what was set, which hints at a verification use case. There is no explicit when-to-use vs. when-not-to-use guidance or any reference to an alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact not in the annotations: results are automatically scoped to the caller's own customer. It omits pagination/limit behavior and return ordering, so the addition is modest.

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 with zero filler; the core operation and its filters are front-loaded and the scope caveat is appended immediately after.

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

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

For a 6-parameter list tool with no output schema and no parameter descriptions in the schema, the description should say more about the unmentioned 'limit' parameter, pagination, and default ordering. It covers the filter surface adequately but leaves the result-shaping behavior undocumented.

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 carry parameter meaning; it does name five of the six params as filter dimensions (status/priority/area/type/project), which is real compensation. But it omits 'limit' entirely and gives no value formats, defaults, or multiplicity beyond the enum values in the schema.

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

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

States a specific verb and resource (list support tickets) plus the filterable dimensions, so an agent can distinguish it from the singular get_support_ticket and the file_support_ticket mutation. It does not explicitly name or differentiate against those siblings, but the scope sentence makes the operation unambiguous.

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

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

The filter list implies when the tool is useful (browsing/searching tickets by attribute), and the 'scoped to your own customer automatically' clause gives context about result scope. However, there is no explicit when-to-use versus get_support_ticket or when-not guidance, so usage is only 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context that values are not secrets and need no masking, but omits return format, pagination, or project-resolution 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?

Two tight sentences, front-loaded with the core action and clarifying the non-secret nature, then routing to the sibling. No wasted words.

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

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

For a simple 2-param read tool with strong annotation coverage, the description covers the key distinction (non-secret vs secret) and points to the alternative. Missing parameter guidance for limit/project_id keeps it from a 5.

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% and both parameters (limit, project_id) are undocumented in the schema. The description mentions 'a project's ... variables' implying project_id, but adds no detail on the limit parameter or format. Baseline 3 given minimal compensation.

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

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

States a specific verb (List) and resource (a project's non-secret Function variables, including values). It distinguishes itself from list_secrets, though it doesn't explicitly differentiate from other list_* siblings like list_functions or list_deployments.

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

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

Explicitly routes the agent to list_secrets for credentials, providing a clear when-to-use-this-vs-alternative signal. However, it doesn't state when-not to use it or list other relevant 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?

Goes well beyond the annotations: annotations only say idempotentHint=true, non-destructive, closed-world, while the description explains that re-calling updates rather than fails, that no credential passes through the tool (credential_key is a secret NAME), that email has a platform fallback but Slack/WhatsApp do not deliver until configured, and that this sets the project default subject to tenant overrides.

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?

Information-dense and front-loaded with the core action, then layered by concern (provider choice, credentials, idempotency, fallbacks). Every sentence carries weight, though the multi-paragraph density is on the heavy side for a single tool.

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

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

For an 8-parameter mutation tool with nested config and no output schema, the description covers the tricky operational details an agent needs: credential handling, provider selection pitfalls, idempotent re-runs, per-channel fallback behavior, and scope of the default. Nothing material is left unstated.

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 adds real meaning: provider behavior differences, that config.username is a LOGIN name defaulting to from_address with per-provider values, and the distinction that credential_key is a name not a live token. These enrich rather than restate the schema.

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

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

The opening sentence names a specific verb (Configure) and resource (how a project delivers notifications on one channel) and immediately scopes it by excluding message text, naming the sibling set_notification_template that owns that concern. An agent can distinguish this from delete_notification_channel and set_notification_template without opening any 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?

Gives explicit when-to-use guidance: use 'smtp' vs 'ses' with the reason ('ses' can only send as aaly.io), the Slack flow requiring set_secret first, and the note that a tenant can override via REST otherwise unreachable here. Alternatives and preconditions are named, not 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 declare idempotentHint=true and destructiveHint=false, and the description reinforces this ('updates the existing template rather than failing'). Beyond that it discloses non-obvious behavior: Mustache interpolation with HTML-escaped {{value}} vs raw {{{value}}}, per-channel required fields, and the WhatsApp/Meta pre-approval constraint that refuses arbitrary composed bodies.

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?

Four tight paragraphs, each doing distinct work (rendering semantics, keying/upsert, per-channel requirements, defaults). Dense and front-loaded, though the WhatsApp rationale could be trimmed slightly without losing meaning.

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

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

For a 9-parameter setter with no output schema, the description covers what an agent needs: rendering rules, upsert semantics, per-channel field requirements, and interaction with platform defaults. Return values are not needed since annotations confirm a safe, idempotent write.

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 89% (baseline 3), but the description adds conditional meaning the schema's flat per-field docs cannot express: email needs subject+body_text with body_html optional, slack/in_app need body_text, and whatsapp requires provider_config.templateName. This goes beyond the schema's field-level descriptions.

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

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

The opening sentence states a specific verb and resource ('Set the message a notification sends') and immediately scopes it to per-send Mustache rendering. An agent can distinguish this from set_notification_channel, list_notification_templates, and delete_notification_template without opening any 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 gives clear context: templates are keyed per (key, channel_type), calling again updates rather than fails, and templates override shipped auth defaults. However it never explicitly names a sibling alternative or a when-not condition (e.g. when to configure the channel first), so it falls short of full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: no value is ever accepted, credentials must not transit agent context or transport, the call returns human-facing instructions, single-string vs structured token-set secrets rotate atomically, and the write targets the project DEFAULT with tenant override via REST. That is far beyond the annotation payload.

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 paragraphs, each earning its place, with the single most important constraint ('NO VALUE IS ACCEPTED HERE') front-loaded in caps. Slightly longer than strictly necessary for the atomic-rotation detail, which is why it is not a 5.

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

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

There is no output schema, so the description compensates by describing what the call returns (instructions plus the exact key name for a human). Combined with the parameter and safety context, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds meaning by explaining how the key surfaces at runtime (req.secrets['KEY']) and by clarifying the project_id/DEFAULT-vs-tenant-override semantics that the schema only gestures at.

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+resource+outcome ('Register a credential a project's Functions read at runtime') and immediately distinguishes itself from the sibling set by stating that no value is accepted and that it emits operator instructions. An agent can separate this from set_variable, list_secrets and delete_secret without reading schemas.

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

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

It states the trigger clearly ('Call this to declare which secrets a Function needs, then hand the operator that list') and implies the hand-off workflow. It does not explicitly name an alternative tool or a when-not condition, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds material context the annotations cannot: values are stored and returned in plain text, and the write only affects the project default, not tenant overrides. It does not cover return payload or idempotency semantics, but the behavioral picture is strong.

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

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

Three tight sentences, front-loaded with the core action, followed by the set_secret routing and the scope caveat. No filler, though the third sentence is somewhat dense. Every sentence contributes.

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 4-param mutation with no output schema, the description supplies the security posture, the alternative tool, and the default-vs-override scope. An agent has enough to call it correctly; only return/response behavior is unspecified, which is moot given no output schema.

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

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

Schema coverage is 100%, so the schema already documents all four parameters (including the AWS_/AALY_ naming restriction). The description references req.env['KEY'] reading syntax, adding slight meaning, but largely the schema carries this dimension. Baseline 3 is correct.

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

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

States a specific verb (Set) plus resource (NON-SECRET configuration value) and even gives the runtime access path req.env['KEY']. It directly distinguishes itself from the sibling set_secret by naming the boundary between the two.

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

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

Explicitly says when NOT to use it: anything unreadable like an API key or OAuth token belongs in set_secret instead. It also clarifies scope (this sets the project default; tenant overrides are not reachable here), which prevents misuse.

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 cover the safety profile (idempotent, non-destructive, closed-world), and the description layers on genuinely new behavioral facts: all-or-nothing atomic rejection when an immutable field is passed, and the cross-tool identity constraint shared with update_field/update_function. This is context the agent could not get from structured fields 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?

Front-loads what the tool does, then the immutability constraint, then the recovery workflow — a logical order with no filler. The multi-step workaround sentence is dense but each clause carries necessary routing information, so it earns its length.

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

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

For a 9-param mutation tool with no output schema, the description covers the key hazards (immutability, atomic rejection, alternatives) and annotations cover the rest of the safety profile. It omits what a successful response looks like, which is a minor gap given no output schema is declared.

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 56%, so descriptions here do part of the work: the immutable fields and the enabled kill-switch are already documented in the schema itself. The description restates the immutability rule and groups the updatable fields but adds no format, valid-value, or naming detail (e.g. auth enum semantics, label length) beyond the schema, so this lands at the mid baseline.

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

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

States a specific verb (update) and resource (custom endpoint route) and enumerates exactly which attributes are mutable (auth mode, execution mode, enabled state, metadata). An agent can distinguish it from list_endpoints, create_endpoint and delete_endpoint immediately.

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

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

Explicitly warns that entity_id/action/method are immutable and that passing them rejects the call, then names the alternative workflow (create_endpoint + create_function + delete_function + delete_endpoint) for changing those fields. This is a textbook when/when-not with an alternative path spelled out.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scope constraint that field definitions are untouched, but omits whether omitted parameters are preserved (partial vs full update) and what the response contains.

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 lean sentences with no waste; the scope boundary is placed immediately after the purpose statement so an agent reads the constraint before deciding to call.

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?

Adequate for a five-parameter mutation with annotations covering idempotency and safety, but it leaves the plural_label parameter undocumented and says nothing about partial-update behavior or the return value, which matters with no output schema present.

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

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

Schema coverage is only 20% (only entity_id documented), so the description must compensate. It names three of the five parameters (label, description, methods) but gives no format or value semantics for them, and plural_label is never mentioned in either the schema or the 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?

States a specific verb (update) and resource (entity metadata) and enumerates the mutable fields, so the scope is unambiguous. It also draws a boundary against field-related mutation, distinguishing it from update_field and update_entity's field cousins, though it never names a sibling explicitly.

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 negative scope statement ('Does not affect field definitions') implies when this tool is the wrong choice, but there is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative tools (update_field) for changing field definitions.

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 cover only idempotency and non-destructiveness; the description adds substantial behavior the schema can't express: whole-call atomic rejection when any immutable attribute is passed, no silent drops/partial applies, stale-data-readable footgun from delete+recreate, and automatic faceting tied to search immutability. Rich context well beyond structured fields.

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?

Front-loads the highest-value content (MUTABLE/IMMUTABLE lists and the atomicity warning) so an agent gets the critical constraint first. Dense but justified given the footgun complexity, though the trailing 'facet' note is somewhat tangential.

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

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

For a mutation tool with no output schema, it covers atomicity, immutability constraints, migration guidance, and even corrects a likely false assumption about a 'facet' attribute. An agent has everything needed to invoke it safely.

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 80%, so the schema already documents individual params, but the description adds critical meaning the schema lacks: the mutable/immutable partition (type, unique, search, targets, etc. are immutable) and the atomic-rejection rule for mixing them. This is genuine semantic value, though per-parameter syntax is left to 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?

States a specific verb+resource ('Update a field's behavior or metadata') and immediately distinguishes itself from sibling tools by enumerating which attributes are mutable vs immutable. An agent can tell it apart from create_field/delete_field without opening any 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?

Explicitly says what not to do (don't echo back a full field record, don't delete_field+create_field under the same name), the atomicity consequence, and names the precise alternatives (create a differently-named field and migrate per-tenant, the `migrate-field` prompt, the capabilities resource). Nothing is left 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?

Beyond the provided annotations (readOnlyHint=false, idempotentHint=true), the description discloses two high-value traits: changes propagate within 30s without redeploy, and an immutable-parameter violation is atomic ('rejects the whole call, with nothing applied'). That is exactly the operational context an agent cannot infer from the annotation set.

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 filler. The mutation scope and effect are front-loaded, with the failure-mode caveat second, which is the right ordering for a caller deciding whether to invoke.

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 14-parameter mutation tool with no output schema, the description covers scope, immutability, atomicity and propagation latency well. The one notable omission is whether omitted fields are left unchanged (partial update) or cleared, which matters for a bulk-metadata updater.

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 36%, so the description carries real weight: it names all eight mutable parameters and confirms which four are immutable, aligning with the schema's IMMUTABLE markers. It does not clarify semantics such as patch-vs-replace or timeout_ms units, leaving a modest gap.

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

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

States a specific verb ('Update') plus resource ('a Function's mutable metadata') and enumerates exactly which fields are mutable, so an agent can distinguish it from create_function, delete_function and the sibling update_* tools without opening any 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?

The mutable/immutable split functions as a clear when-to-use/when-not guide: it warns that entity_id, name, trigger_point and language will reject the entire call. It does not name alternative tools explicitly, so it stops just short of the top band.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful boundary ('does not affect the data table or schema'), though it omits partial-update behavior for the 0-required-parameter semantics.

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, purpose front-loaded, second sentence adding scope with zero waste. Nothing redundant.

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

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

With 100% schema coverage, annotations covering safety, and no output schema, the definition gives an agent everything needed to call correctly. Only the absence of any when-to-use routing keeps it from a 5.

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 each parameter carries rich guidance (e.g., multiTenant/publicSignup interaction, emailVerification lock-out warning). The description only names the fields without adding format or interaction detail, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Update project metadata') and enumerates the affected surface (name, description, flags, email verification/branding). The scope boundary 'Does not affect the project's data table or schema' helps distinguish it from update_field/update_entity, though it doesn't name create_project or describe_project explicitly.

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?

Clarifies what is and isn't affected, implying it's for mutating project-level settings rather than schema/data. However, it gives no explicit when-to-use routing versus siblings like describe_project or create_project, and no prerequisites for invoking 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 only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds far more: a 100MB server-enforced cap, an ~8MB practical ceiling on base64 args, a transport-agnostic guarantee (no local FS needed), and the two-phase presign-then-register flow with the exact form-field naming rule ('file' last). This is well beyond what structured fields provide.

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

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

Front-loads the purpose and the scope exclusion before the numbered modes, and every sentence carries load (caps, ordering, field naming). The three-mode block plus the 100MB trailer is fairly long, but the complexity of the call genuinely warrants it; only mild tightening is possible.

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

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

With no output schema, the description compensates by describing what mode 2 returns (presigned URL plus uploadFields and the s3_key to feed back), and it closes the loop on error handling by telling the agent what to do when no mode is viable. Nothing needed to call this 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%, so baseline is 3, and the schema descriptions already map each parameter to its mode. The description adds orchestration semantics the schema cannot express — that size is derived automatically in mode 1 but required in modes 2/3, and that s3_key comes from a prior mint-only call — which lifts it above baseline without being strictly necessary.

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

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

States a specific verb (upload) and resource (file into the project's own `files` entity), and immediately delimits scope: platform-project only, not an end-customer's project. It names the sibling behavior an agent might otherwise assume (calling a project's REST API) and rules it out, so it is distinguishable without opening any 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?

Gives three ranked usage modes with explicit selection conditions (small file → content_base64; large file + own HTTP capability → mint presigned URL then register with s3_key; neither → defer to the app UI), plus an explicit when-NOT (end-customer projects). No inference is left 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 declare a non-idempotent write (readOnlyHint false, idempotentHint false), but the description adds the critical operational consequence: there is no per-voter dedupe, so repeated calls inflate the count. This is exactly the kind of behavioral disclosure that prevents agent misuse.

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 differentiator; the second sentence delivers the essential usage constraint. No filler or redundancy.

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

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

No output schema exists, and the description covers purpose, the key alternative, and the non-idempotent behavior. Given the simple one-parameter surface, no critical information is missing.

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

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

Schema description coverage is 0% and the only parameter is a string request_id. The description compensates by identifying the target as an existing feature request, but does not specify format, source, or failure behavior. For a single parameter, this is adequate but not rich.

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

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

States a specific verb ('Add one vote') and resource ('feature request'), and distinguishes it from creating a duplicate. The 'me too' signal clarifies the intent for an existing request.

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

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

Explicitly says to use this for something already filed rather than creating a duplicate, and provides a negative guideline: call once per distinct person/session, not repeatedly for the same requester. Although it does not name the sibling file_feature_request, the alternative is unambiguous from context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses where credentials come from (hosted API key vs. local AALY_TOKEN JWT/API key), what is fetched (platform user record), the exact return surface (user, projects with id/slug/name, key context, default_project_id, hint), and a behavior-changing side effect on other tools. No contradiction with the read-only 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?

Front-loaded with the critical instruction ('ALWAYS CALL THIS FIRST') and every subsequent clause carries functional information about credentials, return shape, and downstream effects. It is dense to the point of being a long single block, but no sentence is 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?

There is no output schema, so the description carries the return contract itself, and it does so by enumerating the returned fields including the `hint`. Together with the credential-source detail and the default_project_id effect, an agent has everything needed to call this correctly on the first turn.

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 takes zero parameters, so the baseline is 4 and the description correctly states 'No parameters.' The discussion of project_id applies to other tools rather than this one's inputs, but it usefully frames why no parameter is needed here.

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

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

Names a specific verb and resource set: it resolves identity from the request token, fetches the user record, and lists projects under the customer. This is clearly differentiated from the sibling list_projects (which lists projects without resolving identity) and from every create_/update_/delete_ sibling.

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

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

Explicitly states 'ALWAYS CALL THIS FIRST in any new conversation', which is about as strong a when-to-use directive as exists. It further explains that a returned default_project_id lets callers omit project_id on create_entity/generate_openapi_spec/describe_project/update_project, so the agent knows the downstream consequences of calling this first.

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