Portravo Construction Takeoff

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

Annotations cover fact of idempotency, non-destructiveness and open-world behavior, but the description adds substantial operational detail beyond them: the 10 MiB and 32 KiB limits, the refusal behavior that prevents overwriting existing work, idempotency-key replay returning the original result, private storage in the connected account, and that no credits are consumed.

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 primary action and size constraints, then routing and refusal semantics. Dense but each sentence carries new information; no filler or restatement of the title, though it is on the longer side.

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 an output schema present, return values need not be described, and the description covers the remaining gaps: input alternatives, size limits, refusal/immutability behavior, idempotency, storage privacy, and credit neutrality. Nothing an agent needs to invoke it correctly is missing.

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

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

At 50% schema coverage the description meaningfully compensates, clarifying the mutually exclusive plan (host download_url + file_id) vs plan_inline (base64 of exact bytes with file_name and application/pdf) choice and their respective size caps. It leaves project_id and the exact idempotency_key format largely to the schema, so it stops just short of full coverage.

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

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

States a specific verb and resource ('Attach a PDF ... as the first plan for a new Portravo project') with clear scope, distinguishing it from siblings like create_project and run_takeoff. An agent can tell immediately what the tool does and what object it operates on.

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-not conditions ('Projects that already have a plan or review work are refused, so existing work is never replaced') and names the fallback path for the case it cannot serve (a linkless PDF over 32 KiB is uploaded in the browser at reviewUrl instead). Alternatives and preconditions are spelled out rather than 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, but the description adds real behavioral detail beyond them: replaying a key returns the original project rather than creating a duplicate, it returns a reviewUrl, and the call does not trigger extraction or consume credits. It omits auth/permission requirements and any uniqueness rules on name.

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 sentences, front-loaded with the action and its inputs, then idempotency, then the return value, then the cost boundary. No filler, though the reviewUrl sentence slightly overlaps the existing output schema.

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?

An output schema exists, so return details need not be restated, yet the description still surfaces reviewUrl for convenience. Combined with annotations, idempotency semantics, and the explicit no-extraction/no-credit statement, an agent has everything needed to invoke this mutation 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 description coverage is 0%, so the description carries the param burden, and it names all four: name, optional address, optional metro_code (flagged as needing a "supported" metro), and the idempotency_key replay behavior. Concrete constraints like max lengths and the key's character pattern remain schema-only.

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 construction estimate project") and scopes it to the connected Portravo account. It also draws the boundary against the write-heavy sibling run_takeoff by noting it "does not run extraction or consume estimate credits," so an agent can distinguish creation from execution.

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 clear context for use: creating a project from name plus optional address/metro_code, with the idempotency_key semantics for safe retries. It does not explicitly name when to prefer a sibling (e.g., list_projects to find an existing one first, or run_takeoff to actually process a plan), so it stops short of full when/when-not 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?

Adds substantial context beyond the readOnly/idempotent/non-destructive annotations: the download is short-lived, exports are scoped to owned estimates, and unreviewed estimates are refused with a specific review_required error carrying a remediation link. This error contract is exactly the behavioral detail an agent needs and cannot get from the schema or 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 that front-load the outcome and precondition before the failure case. 'Never exports unreviewed estimates' largely restates the preceding clause, a minor redundancy, but the definition is far shorter than the amount of useful information it carries.

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 an output schema present, return-value shape need not be described, and annotations already cover the safety profile. The description supplies the prerequisites, the error contract, and the artifact lifetime, leaving nothing an agent needs 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?

Only one parameter (project_id) with 0% schema description coverage, so the schema documents format constraints but not meaning. The description implies ownership scoping ('an owned Portravo estimate') but never says that project_id identifies the project or how ownership is enforced, 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?

Names a specific verb and artifact ('Get a short-lived Excel XLSX download') against a precisely scoped resource ('an owned Portravo estimate after every takeoff line has been reviewed and the estimate is priced or final'). This clearly distinguishes it from siblings like run_takeoff or get_takeoff, which produce or read takeoff data rather than an export.

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?

States the conditions under which the tool succeeds (all takeoff lines reviewed, estimate priced or final) and the failure path (review_required error with a review link). It never names an alternative sibling tool for the not-ready case, but the when/when-not boundary is unambiguous.

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 fully covered. The description adds only the OAuth-linking context; it does not mention auth prerequisites or behavior when unlinked, but with annotations this bar is lower.

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

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

A single short sentence with no filler, and the object of the action ('signed-in account') is front-loaded.

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

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

With an output schema present, the return value need not be described, and rich annotations cover the safety profile, so only usage guidance is missing. For a zero-parameter read tool this is close to complete.

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

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

The tool takes zero parameters, so there is nothing for the description to document; baseline 4 applies. Schema coverage is also 100%.

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 ('Identify') and resource ('the signed-in Portravo account'), and adds the triggering context of OAuth account linking. Siblings are entirely unrelated (projects, takeoffs, pricing markets), so no sibling differentiation is needed; it is clear but not distinctive beyond its own scope.

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

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

The phrase 'after OAuth account linking' implies when this tool is relevant, so usage is implied rather than stated. There is no explicit guidance on when to call it versus alternatives, nor what to do if no account is linked.

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 closed-world, so the safety profile is covered. The description adds non-obvious domain behavior: the ownership constraint on the project, the reviewRequired flag semantics, and the caveat that quantities are not bid-ready — context an agent cannot get from 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 tight sentences with the core purpose front-loaded and no filler. The final caveat sentence is slightly redundant with the preceding reviewRequired sentence but earns its place by clarifying downstream use.

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

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

An output schema exists, so return values need not be enumerated, yet the description usefully names the key fields (quantities, trades, confidence, review status). For a single-parameter read tool this is close to complete; only the provenance of project_id 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?

Only one parameter and schema description coverage is 0%, so the schema documents nothing beyond type/pattern/length. The description partially compensates by establishing that project_id must reference an owned project, but adds no format or sourcing guidance beyond that.

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 (read) and a precisely scoped resource (an owned project's plan files plus extracted takeoff quantities, trades, confidence, and review status). This is clearly distinguishable from siblings like run_takeoff (which presumably generates a takeoff) and list_projects.

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

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

The description implies usage context ('reviewRequired reports whether any line still needs estimator review') and gives a domain caveat about requiring review before pricing/bidding, but never states when to use this versus run_takeoff or how to obtain a project_id. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world behavior, so the safety profile is covered. The description adds genuinely useful cross-tool context beyond that: the returned values are not opaque labels but the exact metro_code enum accepted by create_project, which is information annotations cannot convey.

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 waste, front-loaded with the core action and followed immediately by the one fact an agent needs (what the values are used for). Nothing is redundant with the title or annotations.

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?

An output schema exists, so the description is not obliged to enumerate return values. For a simple, parameterless, read-only lookup, the description plus annotations plus output schema give the agent everything needed to select and 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?

The tool takes zero parameters, so per the baseline this scores 4. The description correctly adds nothing about parameters, which is appropriate for a no-argument enumeration call.

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 ('List the regional construction pricing markets supported by Portravo') and immediately clarifies the semantic role of the result: they are the accepted metro_code values for create_project. An agent can distinguish this enumeration/lookup tool from siblings like create_project or list_projects 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?

By tying the output to create_project's metro_code parameter, it strongly implies the usage context (call this to discover valid inputs for project creation). It stops short of an explicit 'use this before calling create_project' instruction or any exclusion, but the context is clear and leaves little to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description nonetheless adds genuine behavioral context the annotations lack: a fixed page size of 50 and the nextOffset/null termination contract, which an agent needs to paginate correctly.

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

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

Two sentences, zero filler. What the tool returns is stated first and the pagination contract second, so the most decision-relevant information is front-loaded.

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

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

An output schema exists, so return-value structure need not be explained, and the description still supplies the pagination mechanics. For a single-parameter read-only list tool, nothing an agent needs to invoke it correctly is missing.

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

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

There is a single parameter (offset) with 0% schema description coverage, so the description must compensate. It does so by explaining the pagination model — 50 projects per page and nextOffset pointing at the next page or null at the end — which effectively documents how offset is meant to be used, though it never states the parameter's unit or that it must be a multiple of 50.

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 gives a clear verb+resource ('Find construction projects') scoped to the connected Portravo account, and enumerates the estimate statuses covered (draft, review, priced, final), which clarifies scope beyond the title. It does not explicitly contrast with siblings such as create_project, though the read-vs-create distinction is obvious from the verb.

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 'Find construction projects in the connected Portravo account' but there is no explicit when-to-use, when-not-to-use, or named alternative among the siblings (e.g., create_project, run_takeoff). The enumeration of estimate statuses does implicitly tell the agent that no status filter exists, which is mild 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description discloses cost behavior (consumes one estimate credit), refusal conditions, refund on failed provider runs, and the non-destructive guarantee that existing review work cannot be overwritten. This is exactly the operational context an agent needs before spending credits.

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: the primary action leads, followed by prerequisites, cost, and safety behavior. Four sentences all carry load, though the failure/refund clause could be tightened.

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?

An output schema exists so return structure need not be explained, yet the description still sets expectations ('extracted quantities for review, not a bid-ready estimate'). Combined with credit, idempotency, and non-destructiveness notes, an agent has everything needed to call this 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 description coverage is 0%, so the description must carry parameter meaning. It defines confirm_credit_use ('refused unless true') and idempotency_key ('repeating a call with the same key does not charge again') well; project_id is only implied by the surrounding prose rather than explained.

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 (initial AI takeoff for a new project) and pins down the exact precondition (plan PDF attached via attach_plan_pdf or uploaded in Portravo). It is easily distinguished from siblings like get_takeoff or attach_plan_pdf 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 explicitly names the prerequisite step (attach_plan_pdf or a user upload) and the gate (confirm_credit_use must be true), and warns that repeated idempotency keys do not re-charge. It gives clear context for when to call, though it does not explicitly contrast with get_takeoff for retrieving an existing takeoff.

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