Get All Properties

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavior: company_id and project_id default to procore_set_config values, failures return HTTP status codes (401/403/404), and it explicitly states 'Read-only — it changes nothing in Procore.' These details help the agent anticipate behavior. However, the contradictory return-shape description slightly detracts from transparency.

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

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

The description is moderately sized but includes redundancy ('Required parameters: company_id, project_id' repeats the schema) and an internal contradiction about return type. The operational details are useful, but the structure is a bit rambling and contains wasteful repetition.

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

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

There is no output schema, so the description should clarify return values. It mentions 'single JSON object' but also 'list of custom property definitions,' leaving the return shape ambiguous. It does provide error handling, default behavior, and the API endpoint, but lacks clarity on pagination or what 'all' means, making it incomplete for a list-style 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 schema already covers all parameters (100% coverage), so the baseline is 3. The description adds meaningful semantics by explaining that company_id and project_id default to values set by procore_set_config when omitted—useful context not in the schema. It also restates required parameters, but that is redundant. The view parameter is already well-described in the schema.

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

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

The description starts with a clear verb and resource ('Returns the list of custom property definitions available for transfers'), but then contradicts itself by saying 'Returns a single JSON object describing the property.' This ambiguity makes it unclear whether the tool returns a list or a single item. It also does not distinguish itself from sibling tools like get_all_properties_project_v2_0.

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 'Use this when you already know which property you want and need its full field set' provides some usage context, but it is confusing—if you already know the property, a list of all definitions seems counterintuitive. The description does not mention alternatives, exclusions, or when not to use this tool, leaving usage guidance underdeveloped.

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